CNB 文档

简体中文

English

简体中文

English

外观

插件制作

复制页面

903 字约 3 分钟

插件制作 介绍如何从零开发并发布一个云原生构建插件。

使用场景：流水线的某个步骤需要自定义能力、又想在多个事件或仓库间复用时使用——例如把公司 内部的发布流程、代码检查工具封装成插件镜像，供 .cnb.yml 直接引用，无需在每个步骤里重复写脚本。

在 云原生构建 中，一个插件就是一个 Docker 镜像。下面以 Bash 为例，介绍如何从零开发一个镜像插件。 本示例插件的功能是打印 hello world，阅读前请先了解 Docker 基础知识。

设计插件

参数设计

设计插件参数：

  • text: 要输出到控制台的文本内容

支持的参数类型

参数类型支持 字符串、数值、布尔值、一维数组、普通对象。

其中：

  • 数组传给容器时以英文逗号 , 分隔
  • 普通对象传给容器时会转为 JSON 字符串

如果参数结构过于复杂，建议存放到文件中由插件运行时加载， 或简化参数设计、拆分为多个插件。

配置示例：

.cnb.yml
main:
  push:
    - stages:
        - name: hello world
          image: cnbcool/hello-world
          settings:
            text: hello world
            boolean: true
            number: 123
            array: [hello, world]
            map:
              key: value

这些参数会转换为大写并添加 PLUGIN_ 前缀，以环境变量的形式传入容器：

PLUGIN_TEXT='hello world'
PLUGIN_BOOLEAN='true'
PLUGIN_NUMBER='123'
PLUGIN_ARRAY='hello,world'
PLUGIN_MAP='{"key":"value"}'

编写脚本

编写 Bash 脚本打印参数：

#!/bin/sh
echo "$PLUGIN_TEXT"

构建插件镜像

插件以 Docker 镜像的形式分发，需要创建一个 Dockerfile 把脚本打包进去，并设置为 Entrypoint。

FROM alpine

ADD entrypoint.sh /bin/
RUN chmod +x /bin/entrypoint.sh

ENTRYPOINT /bin/entrypoint.sh

构建镜像：

docker build -t cnbcool/hello-world .

测试插件

建议在本地测试插件，使用 docker run 运行，通过环境变量传入参数：

docker run --rm \
  -e PLUGIN_TEXT="hello world" \
  cnbcool/hello-world

测试文件系统访问

插件可以读取构建流程的工作区目录。默认会把构建目录映射到插件容器内的同一路径，并设为工作目录：

docker run --rm \
  -e PLUGIN_TEXT="hello world" \
  -v $(pwd):$(pwd) \
  -w $(pwd) \
  cnbcool/hello-world

导出变量

插件执行完成后，可以通过 ##[set-output key=value] 格式输出结果， 再配合流水线的 exports 将其导出为环境变量，供后续任务使用。

示例：导出 GREETING 变量

假设插件需要将 hello world 导出为变量 GREETING，供后续 Job 使用。

1. 修改插件脚本，输出自定义变量：

entrypoint.sh
#!/bin/sh
echo "$PLUGIN_TEXT"

# 输出自定义变量，供 exports 导出
printf '##[set-output greeting=%s]\n' "$PLUGIN_TEXT"

提示

##[set-output key=value] 会被 CI 解析到 Job 的 result 对象中，之后可通过 exports 导出为环境变量。

2. 在流水线中使用 exports 导出变量，并在后续任务中引用：

.cnb.yml
main:
  push:
    - stages:
        - name: hello world
          image: cnbcool/hello-world
          settings:
            text: hello world
          exports:
            greeting: GREETING
        - name: use greeting
          script: echo $GREETING

运行后，第二个 Job 会输出 hello world。

exports 支持导出脚本执行结果（code、stdout、stderr、info） 和内置任务返回值，详见 环境变量 - 导出环境变量。

发布插件

插件就是一个 Docker 镜像，发布插件即发布镜像。可发布到云原生构建仓库自带的 制品库，也可发布到 Docker Hub 供全球使用。

发布镜像

docker push cnbcool/hello-world
© 2026 cnb.cool