---
url: /zh/build/web-trigger.md
description: |
  介绍如何在 CNB 页面上配置自定义按钮来手动触发流水线， 包括 web_trigger.yml 配置文件的语法说明 及支持传入自定义环境变量的功能。
---
云原生构建支持在页面上配置自定义按钮来手动触发流水线，
点击按钮即可执行 [web\_trigger](./trigger-rule.md#web_trigger) 自定义事件，
同时支持在页面上输入环境变量。

效果如下：

![](/images/build/web-trigger-btn.zh.png)

:::tip
目前仅支持在「代码-分支详情页」上配置自定义按钮。
:::

## 自定义按钮配置

在仓库根目录下创建 `.cnb/web_trigger.yml` 文件来配置自定义按钮。

:::tip

1. `.cnb/web_trigger.yml` 不支持 `include` 和 `imports` 语法。
2. 自定义按钮触发的事件需在 `.cnb.yml` 中配置，否则无法触发。

:::

### 基础示例

最简配置——仅指定按钮名和事件名：

```yaml title=".cnb/web_trigger.yml"
branch:
  - buttons:
      - name: 按钮名4
        description: 按钮描述
        event: web_trigger_four
```

### 分支匹配

通过 `reg` 正则表达式控制按钮在哪些分支详情页显示：

```yaml title=".cnb/web_trigger.yml"
branch:
  - reg: ^release
    buttons:
      - name: 发布
        event: web_trigger_release

  - reg: ^dev
    buttons:
      - name: 开发构建
        event: web_trigger_dev

  - buttons:
      - name: 通用操作
        event: web_trigger_common
```

### 环境变量（env）

通过 `env` 传入预置环境变量，支持简单值和带别名的格式：

```yaml title=".cnb/web_trigger.yml"
branch:
  - reg: ^release
    buttons:
      - name: 发布
        event: web_trigger_release
        env:
          a: 1
          b: 2
          c:
            name: 变量c
            value: 3
```

### 可输入环境变量（inputs）

通过 `inputs` 允许用户在执行时手动输入变量，支持八种输入类型：`input`、`textarea`、
`select`、`switch`、`radio`、`date`、`datetime`、`daterange`。

```yaml title=".cnb/web_trigger.yml"
branch:
  - reg: ^release
    buttons:
      - name: 发布
        event: web_trigger_release
        inputs:
          var1:
            name: 版本号
            type: input
            required: true
            default: 1.0.0
          var2:
            name: 环境
            type: select
            default: staging
            options:
              - name: 开发环境
                value: dev
              - name: 预发布
                value: staging
              - name: 生产环境
                value: production
```

其他输入类型详见下方 [Button 类型定义](#button-类型定义) 中的 `inputs` 字段。

### 日期选择器（date / datetime / daterange）

`inputs` 支持三种日期选择器类型：`date`（日期）、`datetime`（日期时间）、`daterange`（日期范围）。

```yaml title=".cnb/web_trigger.yml"
branch:
  - buttons:
      - name: 定时发布
        event: web_trigger_scheduled_release
        inputs:
          release_date:
            name: 发布日期
            description: 选择计划发布的日期，将作为环境变量注入流水线
            type: date
            required: true
            # 默认值必须加引号，避免被 YAML 解析为 Date 对象
            default: "2026-08-01"
            min: "2026-01-01"
            max: "2026-12-31"
          release_at:
            name: 发布时刻
            description: 精确到分钟的发布时间
            type: datetime
            format: "YYYY-MM-DD HH:mm"
            default: "2026-08-01 10:00"
          range:
            name: 活动区间
            description: 活动的起止日期，用于生成灰度窗口
            type: daterange
            # daterange 默认值用逗号分隔起止日期
            default: "2026-08-01,2026-08-31"
```

传给流水线的环境变量：

```text
release_date=2026-08-01
release_at=2026-08-01 10:00
range=2026-08-01,2026-08-31
```

::: tip

1. 默认值必须用引号包裹（如 `"2026-08-01"`），否则会被 YAML 解析为 Date 对象。
2. `daterange` 的默认值和最终传值都用英文逗号分隔起止日期。
3. 日期按用户浏览器本地时区显示与选择，最终以字符串形式作为环境变量注入流水线。

:::

### 权限控制

通过 `permissions` 限制可触发构建的用户或角色：

```yaml title=".cnb/web_trigger.yml"
branch:
  - reg: ^release
    buttons:
      - name: 发布
        event: web_trigger_release
        permissions:
          roles:
            - master
            - developer
          users:
            - name1
            - name2
```

### 按钮分组

通过 `groupName` 将按钮分组显示，不同分组间有分割线：

```yaml title=".cnb/web_trigger.yml"
branch:
  - reg: ^feature
    buttons:
      - name: 构建项目
        event: web_trigger_build
        groupName: 构建操作
      - name: 运行测试
        event: web_trigger_test
        groupName: 构建操作
      - name: 部署预发布
        event: web_trigger_deploy
        groupName: 部署操作
```

### inputs 分组

inputs 也支持分组，适用于参数较多的场景：

```yaml title=".cnb/web_trigger.yml"
branch:
  - reg: ^dev
    buttons:
      - name: 构建
        event: web_trigger_dev
        inputs:
          - name: 基础配置
            collapsed: false
            inputs:
              var1:
                name: 版本号
                type: input
                required: true
              var2:
                name: 环境
                type: select
                options:
                  - name: 开发
                    value: dev
                  - name: 测试
                    value: test
          - name: 高级配置
            inputs:
              var3:
                name: 模块
                type: select
                multiple: true
                options:
                  - name: 模块A
                    value: module-a
                  - name: 模块B
                    value: module-b
              var4:
                name: 部署策略
                type: radio
                options:
                  - name: 滚动更新
                    value: rolling
                  - name: 蓝绿部署
                    value: blue-green
```

### 其他特性

**默认按钮**：设置 `isDefault: true` 后点击按钮直接弹出该按钮的构建弹框（仅一个生效）。

**启动云原生开发**：设置 `openWorkspace: true`，触发构建后直接进入云原生开发启动页：

```yaml title=".cnb/web_trigger.yml"
branch:
  - buttons:
      - name: 启动开发环境
        event: web_trigger_launch_vscode
        openWorkspace: true
```

**description 变量替换**：`description` 支持引用 `env` 和 `inputs` 中的变量（仅支持替换一级）：

```yaml title=".cnb/web_trigger.yml"
branch:
  - buttons:
      - name: 按钮6
        description: ${desc}
        event: web_trigger_six
        env:
          desc: 按钮描述
```

目前仅支持配置分支详情页的自定义按钮。YAML 中键名为 `branch`，值为数组格式：

* `reg`：选填，`String`，正则表达式，用于匹配分支名
  （仅匹配到的分支显示 `buttons` 配置的自定义按钮）。未填则匹配全部分支。
* `buttons`：必填，`Array<Button>`，自定义按钮定义。`Button` 类型定义如下：
  * `name`：必填，`String`，自定义按钮名
  * `description`：选填，`String`，按钮描述。如存在，将作为流水线 title，否则使用默认 title；
    支持环境变量替换（仅支持替换一级，环境变量指当前配置的 env 和 inputs，仅支持 ${xxx} 写法）
  * `image`：选填，`String`，自定义按钮图标。只能用本仓库中当前分支的图片，填写相对仓库根目录的路径，如 .cnb/button.png
  * `event`：必填，`String`，触发的 CI 事件名，需要在 `.cnb.yml` 中配置。
    仅支持 [web\_trigger](./trigger-rule.md#web_trigger) 自定义事件。
  * `isDefault`：选填，`Boolean`，是否为默认按钮，仅支持设置一个
    （设置多个时取第一个）。设置默认按钮后，点击按钮直接弹出默认按钮的
    触发构建弹框；未设置时，点击按钮弹出包含所有自定义按钮的弹层。
  * `groupName`：选填，`String`，按钮分组名。
    相同 `groupName` 的按钮会分组显示在一起，分组名会作为标题显示在按钮上方，
    不同分组之间有分割线隔开。未配置 `groupName` 的按钮归为同一组。
  * `openWorkspace`：选填，`Boolean`，是否启动云原生开发环境。
    开启后触发构建将直接进入云原生开发的启动页。
    非云开发场景请勿配置此参数。
  * `env`：选填，`Object<String, String|EnvType>`，传给 web\_trigger 自定义事件流水线的默认环境变量，不支持编辑。
    对象键值为环境变量名；
    对象值支持两种格式，`String` 和 `EnvType`。`EnvType` 类型定义如下：
    * `name`：必填，`String`，环境变量别名。非传给流水线的环境变量名
    * `value`：必填，`String`，环境变量值
  * `permissions`：选填，权限控制，满足 `users` 或 `roles` 之一即可触发构建
    （还需仓库写权限）。未配置时，有仓库写权限即可触发。
    * `users`：选填，`Array<String>`，用户名数组。可定义多个。
    * `roles`：选填，`Array<String>`，仓库角色数组。仅支持具备仓库写权限的角色：
      `owner`（负责人）、`master`（管理员）、`developer`（开发者）。
      角色为向上包含，例如仅声明 `master` 有权限，`owner` 仓库权限更高，同样也有权限。
  * `inputs`：选填，`Object<String, Input>`，可手动输入的环境变量，对象的键值为变量名，`Input` 类型定义如下：

    * `name`：必填，`String`，输入选项名称，非环境变量键值，仅用于页面展示
    * `description`：选填，`String`，描述信息
    * `placeholder`：选填，`String`，输入框内提示信息。仅当 type=`input`、`textarea`、`select`、
      `date`、`datetime`、`daterange` 时有效
    * `required`：选填，`Boolean`，是否必填
    * `type`：选填，`String`，输入框类型，可选 `input`、`textarea`、`select`、`switch`、`radio`、
      `date`、`datetime`、`daterange`，默认为 `input`
    * `default`：选填，`String`，默认值。
      `date` / `datetime` 填写符合 `format` 的日期字符串（如 `"2026-08-01"`、`"2026-08-01 10:00"`），
      `daterange` 使用英文逗号分隔的起止日期（如 `"2026-08-01,2026-08-31"`），
      **均需加引号避免被 YAML 解析为 Date 对象**
    * `multiple`：选填，`Boolean`，是否支持多选，仅当 type=`select` 时有效，
      多选结果用分号分隔。单个选项的 `value` 中需避免出现逗号
    * `options`：选填，`Array<Option>`，当 `type: select` 或 `type: switch` 时的选项。`Option` 类型定义如下：
      * `name`：必填，`String`，选项名
      * `value`：必填，`String`，选项值，作为环境变量值
      * `description`：选填，`String`，选项描述信息
    * `format`：选填，`String`，日期系类型（`date` / `datetime` / `daterange`）的格式化模板。
      默认：`date` 为 `YYYY-MM-DD`，`datetime` 为 `YYYY-MM-DD HH:mm:ss`，`daterange` 为 `YYYY-MM-DD`
    * `min`：选填，`String`，日期系类型允许选择的最早日期（含边界，日期字符串如 `"2026-01-01"`）
    * `max`：选填，`String`，日期系类型允许选择的最晚日期（含边界，日期字符串如 `"2026-12-31"`）

    `inputs` 也支持分组，`Array<Object>`，每个数组元素是一个对象，表示一个分组，类型定义如下：

    * `name`：必填，`String`，分组名称，非环境变量键值，仅用于页面展示
    * `collapsed`：非必填，`Boolean`，是否默认折叠该分组，默认为 `false` 不折叠
    * `inputs`：必填，`Object<String, Input>`，分组内环境变量定义，
      对象的键值为变量名，`Input` 类型定义同上方 `Input`类型定义。

## 自定义 web\_trigger 流水线

`.cnb/web_trigger.yml` 中的自定义按钮仅支持触发
[web\_trigger](./trigger-rule.md#web_trigger) 自定义事件，
需在 `.cnb.yml` 中配置对应的流水线。

```yaml title=".cnb.yml"
release*:
  web_trigger_one:
    - stages:
        - name: 输出环境变量
          script:
            - echo $a
            - echo $b
            - echo $var1
            - echo $var2
            - echo $var3
```

**`dev*` 分支的 web\_trigger 事件：**

```yaml title=".cnb.yml"
dev*:
  web_trigger_two:
    - stages:
        - name: 执行任务
          script: echo "job"

  web_trigger_three:
    - stages:
        - name: 执行任务
          script: echo "job"
```

**所有分支的 web\_trigger 事件：**

```yaml title=".cnb.yml"
"**":
  web_trigger_four:
    - stages:
        - name: 执行任务
          script: echo "job"
```

## 权限说明

仅有仓库写权限的用户可点击自定义按钮执行 `web_trigger` 流水线。
若按钮配置了 `permissions`，还需是其中列出的 `users` / `roles` 才能触发。