脚本与插件任务

1333 字约 4 分钟

概述

在 CNB 流水线中，Job（任务）是最小的执行单元，主要分为脚本任务、插件任务和内置任务三种类型。

脚本任务：以镜像作为执行环境，执行用户指定的 Shell 命令
插件任务：运行插件镜像内置的 ENTRYPOINT，通过参数配置行为

两者都支持指定 image，初学者容易混淆。本文说明两者的区别。

核心对比

特性	脚本任务	插件任务
执行方式	`script` / `commands` Shell 命令	镜像内置 `ENTRYPOINT`
执行环境	流水线容器或独立容器	仅独立容器
参数传递	通过 `env` / `imports`	通过 `settings`（→ `PLUGIN_*`）
自定义环境变量	✅ 支持	❌ 不会传递
灵活性	高，可执行任意命令	由插件开发者预设
复用性	与业务强相关	可分享到插件市场

执行环境详情：

脚本任务：未指定 image 时在流水线容器中执行；指定 image 时在独立容器中执行。
插件任务：必须指定 image，始终在独立容器中执行。

未配置 image 的脚本任务在流水线容器中执行
配置了 image 的脚本任务和插件任务在独立容器中执行

只有以下目录在任务间共享，其他目录相互不可见：

CNB_BUILD_WORKSPACE（默认 /workspace）
docker.volumes 中声明的目录

提示

如果上一个任务产生的文件在下一个任务中找不到，请确认文件已写入 CNB_BUILD_WORKSPACE 或已声明的共享目录。

示例

脚本任务

- name: install dependencies
  image: node:20
  script: npm install
  env:
    NODE_ENV: production

插件任务

- name: npm publish
  image: plugins/npm:1.2.3
  settings:
    username: $NPM_USER
    password: $NPM_PASS
    registry: https://registry.npmjs.org/

上述 settings 会注入为环境变量：PLUGIN_USERNAME、PLUGIN_PASSWORD、PLUGIN_REGISTRY。

环境变量传递规则

脚本任务：

✅ env 声明的自定义环境变量
✅ imports 导入的环境变量
✅ CNB 内置系统环境变量
优先级：Job env > Stage env > Pipeline env

插件任务：

✅ CNB 内置系统环境变量
✅ settings / args 中通过 $VAR 引用环境变量
❌ env / imports 声明的自定义环境变量（不会传递）

# ✅ settings 中引用环境变量
- name: npm publish
  image: plugins/npm
  settings:
    username: $NPM_USER

# ❌ env 不会传递给插件
- name: npm publish
  image: plugins/npm
  env:
    PLUGIN_USERNAME: $NPM_USER

为什么插件任务不能通过 env 传递环境变量？

插件任务的设计理念是功能模块化，通过 settings 明确定义插件接受的参数。好处在于：

插件接口清晰，避免参数混乱
插件可以明确声明需要哪些参数
避免环境变量命名冲突，提高可维护性
防止通过环境变量注入引起安全问题

选择建议

场景	推荐	原因
代码构建和测试	脚本任务	灵活控制，适应各种构建工具
自定义业务逻辑	脚本任务	需要完全控制执行流程
消息通知（企微、飞书等）	插件任务	功能内聚，配置简单
通用 CI/CD 操作（发布、部署）	插件任务	插件市场有成熟方案
可复用的通用功能	插件任务	可分享到插件市场

快速判断

有现成插件满足需求？→ 插件任务
需要灵活执行自定义命令？→ 脚本任务
功能可复用分享？→ 插件任务
与业务强相关？→ 脚本任务

最佳实践

版本控制

用到 image 的地方，建议指定镜像版本。使用 latest 时镜像更新可能导致流水线行为变化。

- name: npm publish
  image: plugins/npm:1.2.3
  settings:
    username: $NPM_USER

- name: build
  image: node:20
  script: npm run build

安全性

使用官方或可信的镜像
在密钥仓库中存储敏感信息，避免硬编码
定期检查镜像的安全更新

复用性

插件任务适合封装可复用的功能：

消息通知（企业微信、飞书、钉钉等）
通用 CI/CD 操作（发布、部署等）
代码质量检查（lint、扫描等）

这些功能可以发布到 CNB 插件市场，供其他开发者选用。

脚本任务适合业务相关的逻辑：

代码构建和测试
自定义数据处理
特定业务流程

常见问题

脚本任务不指定 image 会在哪里执行？

在流水线容器环境中执行。流水线容器环境由 Pipeline.docker.image 或 Stage.image 指定，详见构建环境 - 环境作用范围。

如何在插件任务中使用环境变量？

在 settings 或 args 中使用变量替换：

- name: npm publish
  image: plugins/npm
  settings:
    username: $NPM_USER
    password: $NPM_PASS

插件任务可以执行自定义脚本吗？

插件任务可以通过 settings 参数传递脚本内容给插件，但这需要插件本身支持接收并执行脚本。执行逻辑由插件镜像控制，CNB 不直接介入。

脚本任务则不同，script 或 commands 是 CNB 语法原生支持的，由 CNB 在脚本任务指定的 image 或流水线容器环境中直接执行。