942 字约 3 分钟
简介
云原生构建配置文件用于定义代码仓库在特定事件(如推送新 Commit、创建 Pull Request 等)触发时,云原生构建服务是否执行构建任务,以及构建任务中每个步骤的具体操作。
配置文件说明
配置文件规范
- 文件名为
.cnb.yml,存放于代码仓库根目录,遵循“配置即代码” (Configuration as Code) 原则。 - 配置变更可通过 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:22Docker 镜像作为任务执行环境。 - 任务步骤:
- 执行
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.cool/conf-schema-zh.json": ".cnb.yml" } }
Jetbrains

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