NPM Install CNB 镜像文档

一、镜像概述和主要用途

NPM Install CNB 是一个基于 Cloud Native Buildpacks (CNB) 规范的构建组件（Buildpack），旨在通过集成 Node Engine CNB 提供的 npm 工具链，自动化管理 Node.js 应用的依赖项安装流程。其核心功能是在应用构建阶段解析并安装 package.json 中声明的依赖，确保构建环境中依赖项的正确配置，为后续应用打包和运行提供基础。

二、核心功能和特性

2.1 核心功能

• 依赖安装自动化：基于项目根目录的 package.json 或 package-lock.json/yarn.lock（若存在），自动执行 npm install 或 npm ci 命令安装依赖。
• 与 Node Engine CNB 深度集成：复用 Node Engine CNB 提供的 Node.js 运行时和 npm 工具链，确保依赖安装与 Node.js 版本兼容。
• 依赖缓存优化：支持缓存已安装的依赖包（位于 node_modules），减少重复构建时的网络请求和安装时间。

2.2 关键特性

• 遵循 CNB 规范：符合 Cloud Native Buildpacks 标准，可与其他 CNB 构建组件（如 Node Engine CNB、Procfile CNB 等）协同工作，构建 OCI 标准镜像。
• 灵活性配置：支持通过环境变量或配置文件自定义 npm 行为（如私有仓库、安装参数等）。
• 兼容性广泛：兼容标准 Node.js 项目结构，支持包含 package.json 的各类 Node.js 应用（如 Express、React、Vue 等）。

三、使用场景和适用范围

3.1 典型使用场景

• CNB 构建工具链集成：配合 Paketo、Cloud Foundry Buildpacks 等 CNB 构建工具链，实现 Node.js 应用的自动化构建流程。
• CI/CD 流水线依赖管理：在 CI/CD 流水线中作为依赖安装阶段，标准化依赖安装步骤，避免手动配置 npm 环境。
• 标准化构建环境：为团队或组织提供统一的 npm 依赖安装流程，减少因环境差异导致的构建问题。

3.2 适用范围

• 项目类型：包含 package.json 的 Node.js 应用（支持 npm 作为包管理器）。
• 构建工具：兼容 CNB 兼容的构建工具（如 pack CLI、Tekton、GitHub Actions 中的 CNB 插件等）。
• 运行环境：依赖 Node Engine CNB 提供的 Node.js 运行时，支持 Node.js *** LTS 版本及主流稳定版本。

四、详细使用方法和配置说明

4.1 基本使用流程

NPM Install CNB 作为 CNB 构建包，需配合 CNB 构建器（Builder）使用，典型流程如下：

1. 准备项目：确保项目根目录包含 package.json（必要），可选包含 package-lock.json 或 npm-shrinkwrap.json 以锁定依赖版本。
2. 选择构建器：使用包含 Node Engine CNB 和 NPM Install CNB 的 CNB 构建器（如 Paketo Buildpacks 的 paketobuildpacks/builder:base）。
3. 执行构建：通过 pack CLI 或 CNB 兼容工具触发构建，NPM Install CNB 会自动执行依赖安装。

4.2 构建示例（基于 pack CLI）

使用 pack 命令行工具构建 Node.js 应用镜像：

bash
# 安装 pack CLI（参考 [***]
# 构建应用镜像，指定包含 NPM Install CNB 的 builder
pack build my-node-app \
  --builder paketobuildpacks/builder:base \  # 基础 builder，包含 Node Engine 和 NPM Install CNB
  --path ./my-node-project \                # 项目根目录（包含 package.json）
  --env NODE_ENV=production                 # 可选：设置环境变量

构建过程中，NPM Install CNB 会自动执行：

1. 检查项目根目录的 package.json；
2. 通过 Node Engine CNB 提供的 npm 工具运行 npm install（或 npm ci，若存在 lock 文件）；
3. 将安装的依赖（node_modules）缓存至构建层，供后续构建复用。

4.3 配置参数与环境变量

NPM Install CNB 支持通过环境变量或项目配置文件（buildpack.yml/project.toml）自定义行为，常用配置如下：

4.3.1 环境变量

示例：使用私有 npm 仓库构建

bash
pack build my-node-app \
  --builder paketobuildpacks/builder:base \
  --path ./my-node-project \
  --env NPM_REGISTRY=[***] \
  --env NPM_INSTALL_FLAGS="--no-audit --legacy-peer-deps"

4.3.2 项目配置文件

通过项目根目录的 buildpack.yml 或 project.toml 配置（优先级高于环境变量）：

buildpack.yml 示例：

yaml
nodejs:
  npm:
    registry: "[***]"
    install_flags: "--no-audit --legacy-peer-deps"
    config:
      production: true  # 等效于 NPM_CONFIG_PRODUCTION=true

project.toml 示例（符合 CNB 项目元数据规范）：

toml
[[build.env]]
name = "NPM_REGISTRY"
value = "[***]"

[[build.env]]
name = "NPM_INSTALL_FLAGS"
value = "--force"

4.4 依赖缓存管理

NPM Install CNB 会将 node_modules 缓存至 CNB 构建层（/layers/npm-install/node_modules），后续构建时若 package.json 和 lock 文件未变更，将直接复用缓存以加速构建。若需强制刷新依赖（忽略缓存），可通过以下方式：

bash
pack build my-node-app \
  --builder paketobuildpacks/builder:base \
  --path ./my-node-project \
  --env BP_CLEAR_CACHE=true  # 清理所有构建缓存（含依赖缓存）

五、注意事项

1. Lock 文件建议：为确保依赖版本一致性，推荐项目中包含 package-lock.json 或 npm-shrinkwrap.json，此时 NPM Install CNB 会优先使用 npm ci 而非 npm install，减少依赖版本波动。
2. Node.js 版本兼容性：依赖版本需与 Node Engine CNB 提供的 Node.js 版本兼容，可通过 engines 字段在 package.json 中声明 Node.js 版本范围（如 "engines": {"node": ">=18.0.0"}）。
3. 权限问题：构建过程中若需修改 node_modules 权限，可通过 BP_NODE_USER 环境变量指定运行用户（如 --env BP_NODE_USER=root）。