---
url: /zh/build/configuration.md
---
## 简介

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

## 配置文件说明

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

2. **YAML 格式优势**
   * 支持嵌套结构和键值对，清晰表达复杂配置逻辑。
   * 易于扩展和修改，适应动态需求，支持注释提升协作效率。
   * 语法简洁严格，减少配置错误，文件轻量，加载和解析高效。

如需了解更多，请参考[语法手册](./grammar.md)和[触发规则](./trigger-rule.md)。

## 示例配置

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

```yaml title=".cnb.yml"
main: # 目标分支
  push: # 触发事件
    - docker:
        image: node:22 # 流水线执行环境，可使用任意 Docker 镜像
      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:
    # 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
```

**对象形式:**

```yaml title=".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` 表示[触发事件](./trigger-rule.md#trigger-event)。
* 一个事件下可包含多条 `pipeline`（支持数组和对象两种写法），这些 pipeline 会**并发执行**。
* 一条 `pipeline` 包含一组**顺序执行**的 `stages`，它们在同一个构建环境（物理机、虚拟机或 Docker 容器）中运行。

更详细的语法说明请参阅：[语法手册](./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.cnb.share.ralphlauren.cn/conf-schema-zh.json": ".cnb.yml"
     }
   }
   ```

### Jetbrains

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

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