Serverless Framework CI/CD 私有包管理器接入指南：NPM_TOKEN 与 Parameters 的落地实践

本篇技术指南围绕 Serverless Framework Dashboard CI/CD 场景下「私有包管理器（以 NPM 私有注册表为例）的认证接入」展开，讲解如何按官方流程生成认证令牌、如何通过 Serverless Dashboard 的 Parameters 特性将 NPM_TOKEN 注入 CI/CD 执行环境，并结合仓库源码解析 ${param:XXX} 变量在 Dashboard 参数、stages 参数与 CLI 参数之间的解析优先级。读完本文，你能够在 Serverless CI/CD 或自建 CI/CD 流水线中安全地拉取私有依赖包，并理解令牌从 Parameters 到执行环境变量的完整传递链路。

背景：为什么 CI/CD 需要私有包管理器认证

当你的 Serverless Framework 项目依赖私有包管理器（例如 NPM 私有注册表、私有 PyPI 镜像等）时，CI/CD 服务在执行 npm install 等构建步骤前，必须先向私有包管理服务完成身份认证，否则依赖安装会直接失败。

官方文档 Using private package managers 给出的核心结论是：

• 以 NPM 为例，应按 NPM 官方的 CI/CD 私有包指南创建认证令牌（authentication token），得到的令牌将作为环境变量使用；
• 其他运行时（例如 Python）的私有包管理器，通常也提供类似的「基于环境变量的 CI/CD 认证」机制；
• 在 Serverless Dashboard 中，通过 Parameters 特性创建一个名为 NPM_TOKEN 的变量，其值填入你的私有注册表令牌；
• Parameters 定义在与应用和 stage 关联的 deployment profile 中，会被 Serverless CI/CD 服务作为环境变量加载——这就是令牌从 Dashboard 配置到 CI/CD 执行环境的桥梁。

换言之，整套方案由两部分组成：外部私有注册表的令牌生成（一次性操作）+ Serverless Parameters 的密钥托管与注入（持续生效）。

使用 Parameters 注入 NPM_TOKEN

Parameters 是 Serverless Framework 中管理可复配值与安全密钥的核心机制，完整说明见 Parameters 指南。针对私有包场景，关键操作是：

1. 在 Serverless Dashboard 中，定位到目标服务的 deployment profile（即应用 + stage 的组合）；
2. 创建一个名为 NPM_TOKEN 的 Parameter，值设为从私有注册表获取的认证令牌；
3. 之后每次 Serverless CI/CD 触发部署时，该 Profile 下的 Parameters 会作为环境变量加载到 CI/CD 执行环境，npm install 即可凭此令牌访问私有包。

从源码结构看，这一机制有明确实现支撑。参数解析器 param.js 中，resolveVariable 方法将多个参数来源按优先级合并后供 ${param:XXX} 变量使用：

return resolveVariableFromParameters(
  extractCliParams(this.options?.param),      // 1. --param CLI 参数
  this.serviceConfigFile.params?.default,     // 2. params.default
  this.serviceConfigFile.params?.[this.stage],// 3. params.<stage>
  this.serviceConfigFile.stages?.default?.params, // 4. stages.default.params
  this.serviceConfigFile.stages?.[this.stage]?.params, // 5. stages.<stage>.params
  this.dashboard?.params,                     // 6. Dashboard 参数
  this.composeParams,                        // 7. compose 子服务参数
  key,
)

而合并逻辑（同文件 resolveVariableFromParameters 函数）通过对象展开确定了最终优先级，靠后展开的来源优先级更高：

const mergedParams = {
  ...composeParams,
  ...dashboardParams,
  ...defaultConfigParams,
  ...defaultConfigStagesParams,
  ...stageConfigParams,
  ...stageConfigStagesParams,
  ...cliParams,
}

这正对应 Parameters 指南 中描述的解析顺序：--param CLI 参数 > stages.<stage>.params > stages.default.params > Dashboard instance 参数 > Dashboard service 参数，找不到时若提供了 fallback（${param:XXX, 'default value'}）则使用之，否则抛错。

需要注意一个与私有包场景直接相关的安全事实：Dashboard 参数被当作敏感值处理——始终静态加密（encrypted at rest），仅在部署时解密。因此把 NPM_TOKEN 存放在 Deployment Profile 的 Parameters 中，比把令牌硬编码进 serverless.yml 或提交到代码仓库安全得多。

令牌在 CI/CD 构建流程中的实际作用点

在 Serverless CI/CD 的部署流程中（参见 CI/CD 总览），构建步骤本质上是执行依赖安装与 serverless deploy。NPM_TOKEN 作为环境变量被加载后，NPM 客户端在执行 npm install 时依据 .npmrc 中的认证配置向私有注册表出示令牌。典型做法是在项目根目录维护一个 .npmrc，将认证头指向私有注册表：

# .npmrc（提交到仓库，令牌本身只存在于 Dashboard Parameters）
//your-private-registry.example.com/:_authToken=${NPM_TOKEN}

这样令牌值始终来自 CI/CD 环境注入的 NPM_TOKEN 环境变量，而不是出现在版本库中。同理，Python 项目可将私有索引的凭据环境变量（如私有 PyPI 的认证变量）配置为同级的 Dashboard Parameter，在 pip install 阶段由环境变量消费。

如果你不用 Serverless CI/CD，而是在自己的流水线中部署，Running in your own CI/CD 指南 给出了对应的自建环境配置：CI/CD 环境需要预装 Node.js 与 NPM、全局安装 CLI（npm install -g serverless），并通过 SERVERLESS_ACCESS_KEY 环境变量完成对 Dashboard 的认证（非交互环境无法使用 serverless login 打开浏览器）。在此基础上，私有注册表令牌同样遵循「CI/CD 密钥库 → 环境变量 → 构建步骤」的标准链路。

相关环境变量与参数机制的补充

理解 NPM_TOKEN 如何被消费，还有两个值得了解的机制：

1. .env 文件加载。框架会自动从配置目录加载 .env.${stage} 与 .env 文件，实现见 env.js 中的 loadEnvFiles：按「stage 文件先于默认文件、先写者优先（first-write-wins）」的顺序注入环境变量，缺失文件静默跳过，且 process.env 中已存在的变量不会被 .env 文件覆盖。在 CI/CD 场景中，如果平台已把 NPM_TOKEN 注入 process.env，本地调试时也可以通过 .env.prod 等文件提供同名变量（注意不要将真实令牌提交进仓库）。
2. ${env:XXX} 变量引用。serverless.yml 中可用 ${env:SOME_VAR} 引用环境变量（参见 env-vars 变量文档）。但文档同时提醒：经环境变量提供的敏感信息可能被写入保护较弱或可公开访问的构建日志、CloudFormation 模板等处，因此令牌只应被包管理器在构建期消费，避免再透传到函数运行环境或资源模板中。

小结与操作清单

综合 private-packages 文档 与仓库源码，私有包管理器接入的完整操作路径如下：

1. 在私有注册表（如 NPM 私有包）按其官方 CI/CD 指南创建认证令牌；
2. 在 Serverless Dashboard 的目标 deployment profile（应用 + stage）中创建名为 NPM_TOKEN 的 Parameter，填入令牌——该值静态加密存储，部署时解密并以环境变量形式加载到 CI/CD 环境；
3. 在项目中提交仅引用 ${NPM_TOKEN} 环境变量的 .npmrc（或其他运行时对应的认证配置），不提交令牌本身；
4. 本地调试时可通过 .env.${stage} 提供同名变量；若需临时覆盖任意参数，也可使用 serverless deploy --param="key=value"（解析优先级见 param.js 的 resolveVariableFromParameters）。

需要说明的适用前提：本方案面向使用 AWS 作为部署云、Node 或 Python 运行时的 Serverless Framework 项目（见 CI/CD Requirements）；私有注册表的令牌生成细节以其官方文档为准，仓库内文档给出的是接入 Serverless Parameters 机制的通用路径。