---
url: /zh/build/configuration.md
description: |
  介绍云原生构建配置文件 .cnb.yml 的作用、规范及示例， 说明如何通过 YAML 格式定义自动化构建流程。
---
## 简介

云原生构建配置文件定义代码仓库在特定事件（如推送新 Commit、创建 Pull Request）触发时执行的构建任务及各步骤操作。

## 配置文件说明

1. **配置文件规范**
   * 文件名为 `.cnb.yml`，存放于代码仓库根目录，遵循「配置即代码」原则。
   * 配置变更可通过 Pull Request 流程管理，适合开源协作。
   * 构建流程与源代码同步版本控制，确保透明度和变更可追溯。

2. **YAML 格式优势**
   * 支持嵌套结构和键值对，清晰表达复杂配置。
   * 易于扩展和修改，适应动态需求，支持注释提升协作效率。

更多详情请参考[语法手册](./grammar.md)和[触发规则](./trigger-rule.md)。

## 示例配置

以下是一个云原生构建配置示例：

```yaml title=".cnb.yml"
main:
  push:
    - docker:
        image: node:22
      stages:
        - name: install
          script: npm install
        - name: test
          script: npm test
```

### 示例流程说明

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

## 基本语法结构

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

```yaml title=".cnb.yml"
main:
  push:
    - name: push-pipeline1
      stages:
        - script: echo 1
    - name: push-pipeline2
      stages:
        - script: echo 2
```

一个事件下可包含多条 pipeline，支持**数组**（推荐）和**对象**两种写法，
多条 pipeline 会**并发执行**。其中：

* `main` 表示分支名称
* `push`、`pull_request` 表示[触发事件](./trigger-rule.md#trigger-event)
* 一条 pipeline 包含一组**顺序执行**的 `stages`，在同一个构建环境中运行

更详细的语法说明参阅：[语法手册](./grammar.md)

## 配置文件版本选择

配置文件版本的选择规则与[代码版本选择](./trigger-rule.md#代码版本选择)相同。

## 语法检查和自动补全

### VSCode

推荐使用 [云原生开发](../workspaces/intro.md) 环境编写配置文件，其原生支持语法检查和自动补全，效果如下：

![yaml-auto](/images/yaml-auto.gif)

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

1. 安装 `redhat.vscode-yaml` 插件。
2. 在 `settings.json` 配置文件中加入以下内容：

   ```json
   {
     "yaml.schemas": {
       "https://docs.cnbprod.alpha.qq.com/conf-schema-zh.json": ".cnb.yml",
       "https://docs.cnbprod.alpha.qq.com/tag-deploy-schema-zh.json": ".cnb/tag_deploy.yml",
       "https://docs.cnbprod.alpha.qq.com/web-trigger-schema-zh.json": ".cnb/web_trigger.yml",
       "https://docs.cnbprod.alpha.qq.com/settings-schema-zh.json": ".cnb/settings.yml",
       "https://docs.cnbprod.alpha.qq.com/code-security-conf-schema-zh.json": ".cnb/security/code_scan_config.yml"
     }
   }
   ```

### JetBrains

![jetbrains-yaml](/images/jetbrains.png)

1. 打开 `Settings` / `Preferences`。
2. 进入 `Languages & Frameworks` -> `Schemas and DTDs` -> `JSON Schema Mappings`。
3. 点击 `+` 添加新的映射，共添加五条：
   * `https://docs.cnbprod.alpha.qq.com/conf-schema-zh.json` → `.cnb.yml`
   * `https://docs.cnbprod.alpha.qq.com/tag-deploy-schema-zh.json` → `.cnb/tag_deploy.yml`
   * `https://docs.cnbprod.alpha.qq.com/web-trigger-schema-zh.json` → `.cnb/web_trigger.yml`
   * `https://docs.cnbprod.alpha.qq.com/settings-schema-zh.json` → `.cnb/settings.yml`
   * `https://docs.cnbprod.alpha.qq.com/code-security-conf-schema-zh.json` → `.cnb/security/code_scan_config.yml`