Node Run Script CNB 镜像文档

1. 镜像概述和主要用途

Node Run Script CNB 是一个轻量级的 Cloud Native Buildpack (CNB)，专为 Node.js 应用设计，用于在构建或运行阶段执行用户自定义脚本。其核心功能是根据环境变量 BP_NODE_RUN_SCRIPTS 和 package.json 中定义的脚本配置，自动化执行指定的自定义逻辑，简化 Node.js 应用在云原生环境中的构建流程。

2. 核心功能和特性

2.1 核心功能

• 自定义脚本执行：支持执行 package.json 中定义的任意脚本。
• 灵活的脚本指定：通过环境变量 BP_NODE_RUN_SCRIPTS 精确指定需要执行的脚本名称，支持多个脚本按顺序执行。
• CNB 标准兼容：遵循 Cloud Native Buildpack 规范，可无缝集成到 CNB 构建流程中，与其他 buildpack 协同工作。

2.2 主要特性

• 轻量级设计：仅包含执行脚本所需的核心逻辑，无冗余依赖。
• 脚本顺序控制：环境变量中指定的多个脚本按逗号分隔的顺序依次执行。
• 与 Node.js 生态兼容：支持 package.json 标准脚本定义格式，无需额外配置文件。

3. 使用场景和适用范围

3.1 典型使用场景

• 构建前准备：执行代码检查、依赖预处理（如 prebuild 脚本）等操作。
• 构建后处理：完成构建后的资源打包、版本号注入（如 postbuild 脚本）等任务。
• 依赖安装后操作：在 npm install 或 yarn install 后执行自定义初始化逻辑（如 postinstall 脚本）。
• CI/CD 流程集成：在云原生构建流水线中自动化执行自定义业务逻辑。

3.2 适用范围

• Node.js 应用的云原生构建流程（基于 CNB 规范）。
• 需要在构建或运行阶段注入自定义脚本逻辑的场景。
• 与 pack CLI、Tekton、GitHub Actions 等构建工具集成的场景。

4. 使用方法和配置说明

4.1 环境变量配置

4.2 package.json 脚本定义

在应用的 package.json 中定义需要执行的脚本，示例如下：

{
  "name": "my-node-app",
  "scripts": {
    "prebuild": "echo 'Running pre-build checks...'",
    "postinstall": "node scripts/init-db.js",
    "custom-script": "node scripts/custom-logic.js"
  }
}

4.3 集成到 CNB 构建流程

通过 pack CLI 使用该 buildpack 构建应用镜像，示例命令如下：

pack build my-node-app \
  --builder paketobuildpacks/builder:base \
  --buildpack <node-run-script-cnb-buildpack-url> \
  --env BP_NODE_RUN_SCRIPTS="prebuild,postinstall"

参数说明：

• --builder：指定基础构建器（需包含 Node.js 相关 buildpack）。
• --buildpack：指定 Node Run Script CNB 的地址（如 Docker 镜像地址或 Git 仓库）。
• --env BP_NODE_RUN_SCRIPTS：设置环境变量，指定执行 prebuild 和 postinstall 脚本。

4.4 执行流程说明

1. 构建流程启动时，Node Run Script CNB 检测环境变量 BP_NODE_RUN_SCRIPTS。
2. 解析环境变量值，获取需要执行的脚本名称列表（如 prebuild,postinstall）。
3. 按顺序读取 package.json 中对应名称的脚本内容。
4. 依次执行各脚本，输出执行日志，若任一脚本执行失败，构建流程终止并返回错误。

5. 注意事项

• 确保 package.json 中已定义 BP_NODE_RUN_SCRIPTS 指定的所有脚本，未定义的脚本会导致构建失败。
• 脚本执行顺序严格遵循环境变量中逗号分隔的顺序，建议按依赖关系合理排序。
• 该 buildpack 需与 Node.js 基础 buildpack（如 paketo-buildpacks/nodejs）配合使用，确保 Node.js 运行时环境已就绪。