跳到主内容
版本：Next

认证设置

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

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

认证文件位置​

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

  1. <workspace root>/.npmrc — 项目级身份验证。 此文件应列入 .gitignore 中。
  2. <pnpm config>/auth.ini — 主用户级身份验证文件。 pnpm login 在此处写入令牌。
  3. ~/.npmrc — 作为回退被阅读以更容易从 npm 迁移。 使用 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} 的配置行，请务必将该 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​

Added in: v11.10.0

Configures registry authentication as a single structured value, keyed by registry URL. This is an alternative to the many //host/:_authToken=… entries and is designed for CI, where the URL-scoped form (whose variable name contains /, :, and .) cannot be passed through an environment variable on some runners.

_auth is honored only from two trusted locations:

  • the global pnpm config (config.yaml);
  • the pnpm_config__auth environment variable (for CI).

It is ignored in a project pnpm-workspace.yaml or .npmrc, so a checked-out repository can never supply registry auth.

The value is keyed by registry URL, so each secret is explicitly bound to the host that may receive it. Registry URL keys must use http or https and must not include credentials, query strings, or fragments. Within each registry URL, @ means registry-wide (default) credentials, and a package scope such as @org binds credentials to that scope on the same host. The only supported credential field is authToken (it maps to _authToken / bearer auth); the deprecated basicAuth / username + password forms and tokenHelper are not accepted here.

In the global config.yaml:

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

The equivalent environment variable (a JSON string):

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

Both pnpm_config__auth (lowercase) and PNPM_CONFIG__AUTH (all-caps, the convention some CI runners apply) are honored. If both are set, lowercase wins unless it is empty, in which case uppercase is used.

Each entry also infers a trusted registry route: @ routes the default registry (and pnpm add <pkg> resolves there), and @org routes that scope. Because the credential and its destination host arrive in one trusted value, repo-controlled config cannot redirect the token to a different host.

Precedence, from highest to lowest:

  1. CLI flags (--registry, --@scope:registry)
  2. pnpm_config__auth / PNPM_CONFIG__AUTH
  3. global config.yaml _auth
  4. pnpm-workspace.yaml

Parsing is strict: a malformed value (bad JSON, wrong shape, an invalid registry URL or scope, or an unsupported credential field) fails fast with an error rather than being silently dropped.

证书设置​

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
  • 类型：path

包含一个或多个 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
  • 类型：String

访问注册源时传递的客户端证书。 值应为 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
  • 类型：String

访问注册源时要传递的客户端密钥。 值应为 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