简化配置文件

958 字约 3 分钟

精简配置 介绍减少 .cnb.yml 重复内容的几种方式，让配置更易维护。

使用场景：配置文件开始出现重复时使用——例如多个事件复用同一段流水线、多个任务共享环境与缓存设置，或把长配置拆成多个文件按需引用。

YAML 高级语法

由于 .cnb.yml 采用 YAML 格式，可利用 YAML 的锚点 &、别名 * 和合并语法 << 来精简配置、减少重复。

以下示例使用锚点和别名简化配置，展示基础用法和拆分复用：

.cnb.yml
# 定义流水线锚点并在多事件中复用
.pipeline: &pipeline
  docker:
    image: node:22
  stages:
    - name: install
      script: npm install
    - name: test
      script: npm test

main:
  pull_request:
    - <<: *pipeline
  push:
    - <<: *pipeline

单文件内重复较多时，可拆分 stages 为独立锚点：

.cnb.yml
.stages: &stages
  - name: install
    script: npm install
  - name: test
    script: npm test

.pipeline: &pipeline
  docker:
    image: node:22
  stages: *stages

main:
  pull_request:
    - <<: *pipeline
  push:
    - <<: *pipeline

提示

以上是 YAML 自带特性，仅在解析单个 YAML 文件时有效，不能跨文件使用。

此外，锚点会降低可读性：多个分支引用时阅读者需反复跳转才能看清完整配置。当流水线超过 3 次引用同一锚点时，建议改用 include 跨文件复用，或抽取为独立模板文件，使每个文件独立可读。

文件引用

为复用流水线配置，云原生构建提供了以下特性：

include：可以跨文件引用流水线模板。
imports：可以跨文件引用变量。
optionsFrom：可以跨文件引用内置任务参数。
settingsFrom：可以跨文件引用插件任务参数。

详细文件引用说明见文件引用

变量引用

YAML 锚点和别名无法跨文件复用，云原生构建通过以下特性解决该问题：

reference（扩展标签）

YAML 标准不支持跨文件引用。云原生构建通过扩展的 !reference 标签实现按属性路径引用值的功能，可与 include 配合使用，实现跨文件配置复用。

注意

!reference 支持嵌套引用，最多 10 层。
合并配置时，同名的顶层变量会被覆盖，不会深度合并。
解析顺序：先加载并合并所有 include 的文件与主文件 .cnb.yml，然后再解析 !reference 标签。合并过程基于原始文本，不感知引用解析后的值。

示例

a.yml
.val1:
  echo1: echo hello
.val2:
  friends:
    - one:
        name: tom
        say: !reference [.val1, echo1] # 引用本文件内的值

.cnb.yml
include:
  - ./a.yml # 引入 a.yml

.val3:
  size: 100

main:
  push:
    - stages:
        - name: echo hello
          # 跨文件引用 a.yml 中的值
          script: !reference [.val2, friends, "0", say]
        - name: echo size
          env:
            # 引用本文件 .cnb.yml 中的值
            SIZE: !reference [".val3", "size"]
          script: echo my size ${SIZE}

解析后的等效配置：

.cnb.yml
main:
  push:
    - stages:
        - name: echo hello
          script: echo hello # 解析后的值
        - name: echo size
          env:
            SIZE: 100 # 解析后的值
          script: echo my size ${SIZE}

进阶示例：复用整条流水线

.cnb.yml
.common-pipeline:
  - stages:
      - name: echo
        script: echo hello

main:
  push: !reference [.common-pipeline] # 引用整条流水线
test:
  push: !reference [.common-pipeline] # 引用整条流水线

解析后的等效配置：

.cnb.yml
main:
  push:
    - stages:
        - name: echo
          script: echo hello
test:
  push:
    - stages:
        - name: echo
          script: echo hello

VSCode 配置

在 VSCode 中编写带 !reference 标签的 YAML 文件时，需配置以下内容以避免语法报错：

在 settings.json 中添加：

{
  "yaml.customTags": ["!reference sequence"]
}

提示

为避免系统根据 schema 将顶层变量名误识别为分支名而产生错误提示，建议用点号 (.) 开头来命名用于 reference 的顶层变量（例如 .var）。