声明式配置 vs 可视化编排：腾讯云 CNB 用 .cnb.yml 定义研发流程

摘要：

CI/CD 流水线有可视化编排与声明式配置两种方式。本文对比两者差异与适用场景，介绍腾讯云 CNB 用 .cnb.yml 定义研发流程的设计理念、版本可追溯等价值，以及如何用声明式语法定义构建与开发环境。

一、声明式配置与可视化编排的差异

配置 CI/CD 流水线时，团队通常会在两种范式之间做选择：一种是早期 Jenkins 为代表的可视化编排（拖拽式），另一种是以 GitHub Actions、GitLab CI、腾讯云 CNB 为代表的声明式配置（配置即代码）。两者的本质区别在于：流水线定义以何种形态存在、由谁维护、如何变更。

可视化编排通过 Web 界面点击、拖拽来组装构建步骤，上手门槛低，适合不擅长编写配置的成员快速搭建简单流程。但它的定义保存在平台数据库而非代码仓库中，难以纳入版本控制，多人协作时容易出现"谁改了什么、何时改的"说不清的问题，流水线也无法随代码一起评审和回滚。

声明式配置则把流水线写成一份文本文件（通常是 YAML），与源代码放在同一个仓库里。它描述的是"期望达到什么状态"，由编排引擎负责执行，从而把流程定义从某个平台的界面里解放出来，变成可版本管理、可评审、可复用的软件制品。

总体来看，可视化编排适合流程简单、临时性强的小团队；声明式配置更适合追求标准化、合规审计和规模化协作的研发团队。两者并非绝对对立，部分平台也提供"可视化 + YAML"的混合模式，但声明式配置已成为现代云原生研发流程的主流取向。

二、腾讯云 CNB 选择 .cnb.yml 的设计理念

腾讯云云原生构建（Cloud Native Build，简称 CNB）在配置方式上选择了声明式路线，即以 .cnb.yml 文件作为流水线定义的核心载体，采用 YAML 格式，语法简洁直观。这一选择背后是"一切皆代码"（Everything as Code）的设计理念：从构建流水线到开发环境，全部通过声明式配置文件管理，确保一致性和可复现性。

.cnb.yml 文件存放于代码仓库根目录，遵循"配置即代码"原则。这意味着流水线定义不再是独立于代码之外的存在，而是成为代码仓库的一部分：配置变更可通过 Pull Request（PR）流程管理，构建流程与源代码同步版本控制，确保透明度和变更历史可追溯。这一设计尤其契合开源协作场景，让流程定义也能像业务代码一样被评审、被讨论、被复用。

选择 YAML 作为配置格式，也有其工程考量：YAML 支持嵌套结构和键值对，能够清晰表达复杂的构建逻辑；语法简洁严格，有助于减少配置错误；文件轻量、加载高效，且易于扩展和修改以适应动态需求，配合注释也能提升团队协作效率。

三、声明式配置的核心价值

声明式配置带来的价值，集中体现在版本可追溯、与代码同源、可复用和易审计这四个方面，这也是 CNB 坚持 .cnb.yml 路线的关键原因。

版本可追溯：当流水线是一份仓库文件时，每一次修改都会被记录在提交历史中，可以查看是谁、在什么时间、改动了哪个步骤，也能通过提交信息理解变更背景。如果某次流程调整引入了问题，回退到此前可用的状态，只需回退一次提交。

与代码同源：流水线与它所构建的代码处于同一仓库、同一版本。一个改动应用的 PR，可以在同一次提交里同时改动应用代码和流水线，保证"代码版本"与"构建方式"始终对应，避免"代码已经更新、流水线却还是旧版"的错位。

可复用：通用的构建步骤可以沉淀为模板或插件，在不同仓库、不同团队间共享。CNB 也提供丰富的官方和社区插件，团队可以像搭积木一样组合出适合自己的流程，减少重复造轮子。

易审计：对于有合规要求的团队，声明式配置提供了完整的审计线索。因为所有变更都经过版本控制和评审流程，团队能够回答"这次发布用的是哪个版本的构建流程"这类问题，而这是可视化编排难以满足的。

四、.cnb.yml 典型配置结构解析

理解 CNB 的声明式配置，可以从 .cnb.yml 的基本结构入手。它围绕"分支 → 事件 → 流水线 → 阶段 → 任务"层层组织，核心是 Pipeline/Stage/Job 三层结构：

• Pipeline（流水线）：由一次触发事件产生的一次完整执行过程。
• Stage（阶段）：流水线中的执行单元，同一 Pipeline 内的多个 Stage 顺序执行。
• Job（任务）：最小执行单元，在指定的 Docker 容器中运行。

以下是一个典型的配置示例，展示在 main 分支收到 push 事件时，依次执行安装依赖和运行测试：

main:
  push:
    - docker:
        image: node:20
      stages:
        - name: install
          script: npm install
        - name: test
          script: npm test

这段配置的含义是：当 main 分支收到 push 事件时，使用 node:20 Docker 镜像作为执行环境，依次运行 npm install 安装依赖、npm test 执行测试。其中 docker.image 声明了任务运行的环境，stages 列出了要执行的阶段。CNB 会自动为每个阶段拉起隔离的执行环境，任务完成后释放资源。

需要说明的是，.cnb.yml 支持数组和对象两种写法来表达同一事件下的多条流水线；当同一事件匹配到多条流水线时，它们可并行触发（如需让多条流水线互斥执行，还可通过 lock 流水线锁来控制）。更完整的语法细节可查阅官方语法手册，本文仅点到为止，帮助读者建立结构认知。

五、环境即代码：开发环境也用声明式定义

声明式配置的理念不止于构建流水线，CNB 把它延伸到了开发环境管理上，即"环境即代码"。云原生开发能力允许团队通过配置文件声明式地定义开发环境，确保团队成员、不同设备上的环境保持一致，避免"在我机器上是好的"这类经典问题。

借助浏览器端的 Cloud Studio，开发者无需在本地安装任何软件，打开浏览器即可进入标准化的云端开发环境；环境模板可一键创建，也支持通过 WebIDE、VS Code、Cursor 等客户端连接。由于环境本身是用声明式配置描述的，新成员加入时只需拉取仓库、按配置生成环境，即可快速进入开发状态，把过去依赖个人经验的环境搭建，变成了可复现、可共享的团队资产。

把构建流程与开发环境都纳入声明式管理，意味着研发流程中"如何构建"和"在哪开发"这两件关键的事，都有了单一、可信的定义来源，进一步落实了"一切皆代码"的理念。

六、结语

声明式配置与可视化编排代表了两种不同的流水线治理思路：前者以文本文件为载体，换来版本可追溯、与代码同源、可复用和易审计等工程收益，更适合标准化与规模化协作；后者以图形界面见长，适合简单、临时的流程。腾讯云 CNB 选择以 .cnb.yml 声明式 YAML 定义研发流程，正是看中了配置即代码在一致性、协作和合规上的长期价值，并把这一理念从构建流水线延伸到开发环境，实现"环境即代码"。如果你正在搭建或升级团队的 CI/CD 流程，不妨从一份 .cnb.yml 开始体验腾讯云 CNB声明式配置的便捷。