配置文件

974 字约 3 分钟

简介

云原生构建配置文件用于定义代码仓库在特定事件（如推送新 Commit、创建 Pull Request 等）触发时， 云原生构建服务是否执行构建任务，以及构建任务中每个步骤的具体操作。

配置文件说明

配置文件规范
- 文件名为 .cnb.yml，存放于代码仓库根目录，遵循「配置即代码」原则。
- 配置变更可通过 Pull Request (PR) 流程管理，适合开源协作场景。
- 构建流程与源代码同步版本控制，确保透明度和变更历史可追溯。
YAML 格式优势
- 支持嵌套结构和键值对，清晰表达复杂配置逻辑。
- 易于扩展和修改，适应动态需求，支持注释提升协作效率。
- 语法简洁严格，减少配置错误，文件轻量且加载高效。

如需了解更多，请参考语法手册和触发规则。

示例配置

以下是一个简单且可用的云原生构建配置示例：

.cnb.yml
main: # 目标分支
  push: # 触发事件
    - docker:
        image: node:22 # 流水线执行环境，可使用任意 Docker 镜像
      stages:
        - name: install
          script: npm install
        - name: test
          script: npm test

示例流程说明

触发条件：当 main 分支收到 push 事件（即有新 Commit 推送至 main 分支）时，触发构建任务。
执行环境：使用 node:22 Docker 镜像作为任务执行环境。
任务步骤:
- 执行 npm install 安装依赖。
- 执行 npm test 运行测试。

基本语法结构

配置文件的基本结构如下所示：

数组形式（推荐）：

.cnb.yml
# 流水线结构:数组形式
main:
  push:
    # main 分支的 push 事件包含两条流水线
    - name: push-pipeline1 # 流水线名称，可选
      stages:
        - name: job1
          script: echo 1
    - name: push-pipeline2 # 流水线名称，可选
      stages:
        - name: job2
          script: echo 2

  pull_request:
    # main 分支的 pull_request 事件包含两条流水线
    - name: pr-pipeline1 # 流水线名称，可选
      stages:
        - name: job1
          script: echo 1
    - name: pr-pipeline2 # 流水线名称，可选
      stages:
        - name: job2
          script: echo 2

对象形式：

.cnb.yml
# 流水线结构:对象形式
main:
  push:
    # main 分支的 push 事件包含两条流水线
    push-pipeline1: # 流水线名称，必须唯一
      stages:
        - name: job1
          script: echo 1
    push-pipeline2: # 流水线名称，必须唯一
      stages:
        - name: job2
          script: echo 2

  pull_request:
    # main 分支的 pull_request 事件包含两条流水线
    pr-pipeline1: # 流水线名称，必须唯一
      stages:
        - name: job1
          script: echo 1
    pr-pipeline2: # 流水线名称，必须唯一
      stages:
        - name: job2
          script: echo 2

其中：

main 表示分支名称。
push 和 pull_request 表示触发事件。
一个事件下可包含多条 pipeline（支持数组和对象两种写法），这些 pipeline 会并发执行。
一条 pipeline 包含一组顺序执行的 stages，在同一个构建环境（物理机、虚拟机或 Docker 容器）中运行。

更详细的语法说明请参阅：语法手册

配置文件版本选择

配置文件版本的选择规则与代码版本选择相同。

语法检查和自动补全

VSCode

推荐使用云原生开发环境编写配置文件，其原生支持语法检查和自动补全，效果如下：

若在本地 VSCode 中开发，可按以下步骤配置：

安装 redhat.vscode-yaml 插件。

在 settings.json 配置文件中加入以下内容：

{
  "yaml.schemas": {
    "https://docs.cnb.build/conf-schema-zh.json": ".cnb.yml"
  }
}

Jetbrains

打开 Settings / Preferences。
进入 Languages & Frameworks -> Schemas and DTDs -> JSON Schema Mappings。
点击 + 添加新的映射。
设置一个名称。
在 Schema file or URL 中填入：https://docs.cnb.build/conf-schema-zh.json
添加映射文件名 .cnb.yml