跳到主内容
版本：11.x

认证设置

本页设置包含敏感凭据，并以 INI 格式的文件存储。 不要将这些文件提交到你的代码仓库。

对于非敏感设置（代理、SSL、注册源等），请参阅设置（pnpm-workspace.yaml）。

认证文件位置​

pnpm 从以下文件中读取身份验证设置，优先级顺序如下（最高优先）：

  1. <workspace root>/.npmrc — 项目级身份验证。 此文件应列入 .gitignore 文件中。
  2. <pnpm config>/auth.ini — 用户级身份验证主文件。 pnpm login 会将令牌写入此处。
  3. ~/.npmrc — 可作为从 npm 更轻松迁移的备用方案。 请使用 ['npmrcAuthFile']（./settings.md#npmrcauthfile）设置指向另一个文件。

<pnpm config> 目录是：

  • 如果设置了 $XDG_CONFIG_HOME 环境变量：$XDG_CONFIG_HOME/pnpm/
  • 在 Windows 上：~/AppData/Local/pnpm/config/
  • 在 macOS 上：~/Library/Preferences/pnpm/
  • 在 Linux 上：~/.config/pnpm/

认证设置中的环境变量​

用户级认证文件（<pnpm config>/auth.ini 和用户级 .npmrc）中的值可以使用 ${NAME} 语法引用环境变量：

//registry.npmjs.org/:_authToken=${NPM_TOKEN}

自 v11.5.3 版本起，对于以下设置，位于工作区根目录的项目级 .npmrc 文件中的环境变量不会被展开：

  • 注册源和代理 URL（registry、@scope:registry、代理设置）；
  • URL 作用域键（以 // 开头的键）；
  • 凭证值（_authToken、_auth、_password、username、tokenHelper、cert、key）。

如果某项设置在上述任一位置包含 ${...} 占位符，该设置将被忽略，且 pnpm 会输出警告。 项目中的 .npmrc 文件会随代码仓库一同被检出；如果支持在该文件中展开环境变量，恶意仓库便能在安装过​​程中窃取环境中的敏感信息（如 CI 令牌）并将其发送至攻击者控制的注册表 (GHSA-3qhv-2rgh-x77r)。

如果你的项目依赖于一个已提交到版本控制系统的 .npmrc 文件，且其中包含类似 //registry.npmjs.org/:_authToken=${NPM_TOKEN} 的行，请务必将该令牌移至一个安全可靠的位置：

  • 在安装之前（例如在 CI 步骤中），将令牌写入用户级认证文件：

    pnpm config set //registry.npmjs.org/:_authToken "$NPM_TOKEN"

    pnpm config set 默认写入全局位置（认证设置存储在 <pnpm config>/auth.ini 中），而不是项目的 .npmrc 文件，因此令牌不会被提交到代码仓库中。

  • 通过环境变量设置凭证，完全无需 .npmrc 文件（自 v11.6 起）。 pnpm 从 pnpm_config_//… 环境变量中读取针对特定 URL 的注册源设置：

    env "pnpm_config_//registry.npmjs.org/:_authToken=$NPM_TOKEN" pnpm install

    该变量名包含 /、: 和 .，而 export 命令及 NAME=value 这种 Shell 赋值语法会将它们视为无效标识符并予以拒绝。 使用 env 工具（如上所示）将其传递给单个命令，或者通过支持任意变量名的工具（例如 CI 提供商的环境设置或 Node 的 process.env）进行设置。

    这是替代硬编码的 //registry.npmjs.org/:_authToken=${NPM_TOKEN} 这一行的最直接、无需额外文件的方案。 由于该凭证适用的注册源信息被编码在（受信任的）变量名中，恶意仓库无法将其重定向到其他主机。 此类环境变量的值会覆盖项目级的 .npmrc 设置，但会被命令行选项所覆盖。 tokenHelper 设置特意不从环境变量中读取。

  • 或者保留包含 ${NPM_TOKEN} 占位符的那一行，但将其放置在用户级的 ~/.npmrc 文件（或 npmrcAuthFile 指定的文件）中，而不是放在仓库里。

  • 在 GitHub Actions 中，当使用带有 registry-url 输入参数的 actions/setup-node 时，它会将认证配置写入用户级的 .npmrc 文件（该文件由 NPM_CONFIG_USERCONFIG 环境变量指定，且 pnpm 会遵循此变量），因此通过 NODE_AUTH_TOKEN 环境变量进行的认证依然有效。

  • 如果你无法轻松修改每个 CI 流水线，可以通过在 CI 环境中设置单个环境变量（例如在组织或工作区级别）来将项目级的 .npmrc 标记为受信任：

    PNPM_CONFIG_NPMRC_AUTH_FILE=.npmrc

    这是 npmrcAuthFile 设置对应的环境变量形式：它让 pnpm 将项目的 .npmrc 文件作为用户级认证文件来读取（相对路径将基于工作目录进行解析），因此其中的环境变量会像往常一样被展开。 由于信任声明来自环境而非仓库，恶意仓库无法代你进行此设置。 npm 风格的 NPM_CONFIG_USERCONFIG 变量也会作为备选方案被识别。

    警告

    仅在专门构建受信任仓库的环境中使用此设置。 它完全禁用了针对该检出仓库的此项保护，包括关于 tokenHelper 仅可在用户级配置中设置的限制。

同样的规则也适用于项目 .npmrc 文件中的 注册源和代理 URL*（即 registry、@scope:registry、proxy、https-proxy 和 http-proxy）。 如果你使用了环境变量来构建注册源 URL，请将该设置迁移至可信来源——即用户级的 ~/.npmrc 文件，或使用命令 pnpm config set "<key>" <value> 进行设置。 如果该 URL 不涉及敏感信息，你也可以直接将解析后的值写入项目的 .npmrc 文件中，因为只有 ${...} 占位符会被忽略。 关于 pnpm-workspace.yaml 中的注册源设置，请参阅 设置。

认证设置​

<URL>:_authToken​

访问指定注册源时要使用的身份验证承载令牌。 例如：

//registry.npmjs.org/:_authToken=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx

你也可以使用环境变量。 例如：

//registry.npmjs.org/:_authToken=${NPM_TOKEN}

环境变量仅在用户级认证文件中展开，而不会在项目级的 .npmrc 文件中展开。 请参阅 身份验证设置中的环境变量。

特定作用域的认证令牌​

添加于：v11.7.0

pnpm 现在支持为不同的包作用域使用不同的认证令牌，即使这些作用域使用相同的注册源 URL。 在认证键的注册源 URL 后面添加包的作用范围：

@org-a:registry=https://npm.pkg.github.com/
@org-b:registry=https://npm.pkg.github.com/

//npm.pkg.github.com/:@org-a:_authToken=ORG_A_TOKEN
//npm.pkg.github.com/:@org-b:_authToken=ORG_B_TOKEN

//npm.pkg.github.com/:_authToken=FALLBACK_TOKEN

当安装或发布 @org-a/* 时，pnpm 会使用 ORG_A_TOKEN；对于 @org-b/*，则使用 ORG_B_TOKEN。 此外，若提供了全局注册表令牌（即上文提到的 FALLBACK_TOKEN），则未匹配到特定作用域的包将回退使用该令牌。

pnpm login --registry=https://npm.pkg.github.com --scope=@org-a 会将令牌写入同一个针对特定作用域的认证键中。

这对按组织或范围发放令牌的注册源（如 GitHub 包）非常有用。 此前，认证方式仅根据注册源 URL 确定，因此共用同一注册源的两个作用域必须共用同一个令牌。

<URL>:tokenHelper​

令牌助手是输出身份验证令牌的可执行文件。 这可以用于 authToken 不是常量值而是定期刷新值的情况，其中脚本或其他工具可以使用现有的刷新令牌来获取新的访问令牌。

助手路径的配置必须是绝对路径，没有参数。 为了安全起见，只允许在用户 .npmrc 中设置该值。 否则，项目可以在项目的本地 .npmrc 中放置一个值并运行任意可执行文件。

为默认注册表设置令牌助手：

tokenHelper=/home/ivan/token-generator

为指定注册源设置令牌助手：

//registry.corp.com:tokenHelper=/home/ivan/token-generator

_auth​

添加于：v11.10.0

将注册源认证配置为以注册源 URL 为键的单一结构化值。 这是针对众多 //host/:_authToken=… 条目的一种替代方案，专为 CI 环境设计；在某些 CI 运行器上，无法通过环境变量传递这种基于 URL 作用域的配置项（其变量名包含 /、: 和 . 字符）。

_auth 仅在以下两个受信任的位置生效：

  • 全局 pnpm 配置文件（config.yaml）；
  • pnpm_config__auth 环境变量（用于 CI）。

它在项目的 pnpm-workspace.yaml 或 .npmrc 中会被忽略，因此检出的仓库无法提供注册源的认证信息。

该值以注册源 URL 为键，因此每个密钥都明确绑定到可能接收它的主机。 注册源 URL 键必须使用 http 或 https，且不得包含凭据、查询字符串或片段。 在每个注册源 URL 中，@ 代表适用于整个注册源的（默认）凭据；而像 @org 这样的包作用域则将凭据绑定到同一主机上的该特定作用域。 唯一支持的凭证字段是 authToken（它对应于 _authToken 或 Bearer 认证）；此处不再接受已弃用的 basicAuth / username + password 形式以及 tokenHelper。

在全局 config.yaml 中：

_auth:
  https://registry.npmjs.org:
    "@":
      authToken: npm-token
    "@org":
      authToken: org-token

等效的环境变量（JSON 字符串）：

export pnpm_config__auth='{"https://registry.npmjs.org":{"@":{"authToken":"npm-token"},"@org":{"authToken":"org-token"}}}'

pnpm_config__auth（小写）和 PNPM_CONFIG__AUTH（全大写，某些 CI 运行器采用的惯例）均会被识别。 如果两者均已设置，则优先使用小写形式；除非小写形式为空，则使用大写形式。

每一项配置还指定了一条受信任的注册表路由：@ 对应默认注册表（pnpm add <pkg> 也会解析至此），而 @org 则对应相应的作用域。 由于凭证及其目标主机包含在同一个受信任的值中，因此受仓库控制的配置无法将令牌重定向到其他主机。

优先级，从高到低：

  1. CLI 标志（--registry、--@scope:registry）
  2. pnpm_config__auth / PNPM_CONFIG__AUTH
  3. 全局 config.yaml 中的 _auth
  4. pnpm-workspace.yaml

解析过程非常严格：格式错误的值（如无效的 JSON、错误的结构、无效的注册源 URL 或作用域，以及不受支持的凭据字段）会立即导致解析失败并报错，而不会被静默丢弃。

证书设置​

ca​

  • 默认值：npm CA 证书
  • 类型：String，Array 或 null

可信的用于注册源 SSL 链接的 CA 签名证书。 值应采用 PEM 格式（也称 “Base-64 encoded X.509 (.CER)”）。 例如：

ca="-----BEGIN CERTIFICATE-----\nXXXX\nXXXX\n-----END CERTIFICATE-----"

设置为 null 时仅允许已知注册商，若指定 CA 证书将只信任指定的证书颁发机构。

通过指定一个证书数组，可以信任多个 CA：

ca[]="..."
ca[]="..."

另见 strictSsl 设置。

cafile​

  • 默认值： null
  • 类型：路径

包含一个或多个 CA 证书的文件路径。 类似于 ca 设置，但允许多个CA， 此外， CA 信息将存储在一个文件中，而不是通过 CLI 指定。

<URL>:CA文件​

定义访问指定注册源时使用的证书颁发机构文件的路径。 例如：

//registry.npmjs.org/:cafile=ca-cert.pem

<URL>:ca​

添加于：v10.25.0

为指定的注册源定义一个内联证书颁发机构证书。 该值必须采用 PEM 编码，就像全局 ca 设置一样，但它只对匹配的注册表 URL 适用 。

//registry.example.com/:ca=-----BEGIN CERTIFICATE-----...-----END CERTIFICATE-----

cert​

  • 默认值： null
  • 类型：字符串

访问注册源时传递的客户端证书。 值应为 PEM 格式（也称 "Base-64 encoded X.509 (.CER)"）。 例如：

cert="-----BEGIN CERTIFICATE-----\nXXXX\nXXXX\n-----END CERTIFICATE-----"

这不是证书文件的路径。

<URL>:cert​

添加于：v10.25.0

定义一个内联客户端证书，以便在访问指定的注册源时使用。 示例：

//registry.example.com/:cert=-----BEGIN CERTIFICATE-----...-----END CERTIFICATE-----

<URL>:证书文件​

定义访问指定注册源时使用的证书文件的路径。 例如：

//registry.npmjs.org/:certfile=server-cert.pem

key​

  • 默认值： null
  • 类型：字符串

访问注册源时要传递的客户端密钥。 值应为 PEM 格式（也称 "Base-64 encoded X.509 (.CER)"）。 例如：

key="-----BEGIN PRIVATE KEY-----\nXXXX\nXXXX\n-----END PRIVATE KEY-----"

这不是密钥文件的路径。 如果你需要引用文件系统而不是内嵌密钥，使用 <URL>&#58;#;密钥文件 。

此设置包含敏感信息。 不要将其写入本地会提交到仓库的 .npmrc 文件。

<URL>:key​

添加于：v10.25.0

为指定的注册表 URL 定义一个内联客户端密钥。

//registry.example.com/:key=-----BEGIN PRIVATE KEY-----...-----END PRIVATE KEY-----

<URL>:密钥文件​

定义访问指定注册源时使用的客户端密钥文件的路径。 例如：

//registry.npmjs.org/:keyfile=server-key.pem