概述

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

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

两者都支持指定 image，初学者容易混淆。本文帮助您快速区分。

核心对比

特性	脚本任务	插件任务
执行方式	执行 script 或 commands 中指定的 Shell 命令	运行镜像内置的 ENTRYPOINT
执行环境	未指定 image 时在流水线容器中执行；指定 image 时在独立容器中执行	必须指定 image，始终在独立容器中执行
参数传递	通过 env / imports 声明环境变量	通过 settings 指定参数（注入为 PLUGIN_ + 大写参数名）
自定义环境变量	✅ 支持	❌ env / imports 不会传递给插件
灵活性	高，可执行任意命令	功能由插件开发者预设
复用性	与业务强相关	功能内聚，可分享到插件市场

执行环境与文件共享

• 未配置 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 操作（发布、部署）	插件任务	插件市场有成熟方案
可复用的通用功能	插件任务	可分享到插件市场

快速判断

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

最佳实践

版本控制

用到 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: plugin with env
  image: plugins/npm
  settings:
    username: $NPM_USER
    password: $NPM_PASS

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

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

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

上一页构建环境

下一页构建节点