Version: 11.x

身份验证设置

此页面上的设置包含敏感凭据，并存储在 INI 格式的文件中。请勿将这些文件提交到你的仓库。

🌐 The settings on this page contain sensitive credentials and are stored in INI-formatted files. Do not commit these files to your repository.

有关非敏感设置（代理、SSL、注册表等），请参阅 Settings (pnpm-workspace.yaml)。

🌐 For non-sensitive settings (proxy, SSL, registries, etc.), see Settings (pnpm-workspace.yaml).

认证文件位置

🌐 Auth file locations

pnpm 按优先顺序（最高优先级优先）从以下文件中读取认证设置：

🌐 pnpm reads authentication settings from the following files, in order of priority (highest first):

<workspace root>/.npmrc — 项目级别的权限。此文件应列在 .gitignore 中。
<pnpm config>/auth.ini — 主要的用户级认证文件。pnpm login 会在这里写入令牌。
~/.npmrc — 可作为 npm 的回退选项以便更容易迁移。使用 npmrcAuthFile 设置来指向不同的文件。

<pnpm config> 目录是：

🌐 The <pnpm config> directory is:

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

认证设置中的环境变量

🌐 Environment variables in auth settings

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

🌐 Values in the user-level auth files (<pnpm config>/auth.ini and the user .npmrc) may reference environment variables using the ${NAME} syntax:

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

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

🌐 Since v11.5.3, environment variables are not expanded in the project-level .npmrc at the workspace root for the following settings:

注册表和代理 URL（registry、@scope:registry，代理设置）；
URL 范围的密钥（以 // 开头的密钥）；
凭证值（_authToken、_auth、_password、username、tokenHelper、cert、key）。

如果某个设置在这些位置的任何一个位置包含 ${...} 占位符，该设置将被忽略，并且 pnpm 会打印警告。项目 .npmrc 会随着仓库一起检出，因此在该位置扩展环境变量可能会允许恶意仓库在安装过程中将来自你环境的秘密（例如 CI 令牌）泄露到攻击者控制的注册表中（GHSA-3qhv-2rgh-x77r）。

🌐 A setting that contains a ${...} placeholder in any of these positions is ignored, and pnpm prints a warning. The project .npmrc is checked out together with the repository, so expanding environment variables there would allow a malicious repository to exfiltrate secrets from your environment (such as CI tokens) to an attacker-controlled registry during installation (GHSA-3qhv-2rgh-x77r).

如果你的项目依赖于包含类似 //registry.npmjs.org/:_authToken=${NPM_TOKEN} 行的已提交 .npmrc，请将令牌移动到受信任的位置：

🌐 If your project relied on a committed .npmrc containing a line like //registry.npmjs.org/:_authToken=${NPM_TOKEN}, move the token to a trusted location instead:

在安装之前将令牌写入用户级别的认证文件（例如，在 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 变量也会被作为备用方式认可。

danger
仅在专门构建受信任仓库的环境中使用此选项。它会完全禁用已检出仓库的此保护，包括对 tokenHelper 只能在用户级配置中设置的限制。

同样的规则适用于项目 .npmrc（registry、@scope:registry、proxy、https-proxy、http-proxy）中的注册表和代理 URL。如果你使用环境变量来构建注册表 URL，请将此设置移到可信来源——你的用户级 ~/.npmrc 或 pnpm config set "<key>" <value>。如果 URL 不是机密的，你也可以直接在项目 .npmrc 中写入解析后的值，因为只有 ${...} 占位符会被忽略。有关 pnpm-workspace.yaml 中的注册表设置，请参见设置。

身份验证设置

🌐 Authentication Settings

<URL>:_authToken

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

🌐 Define the authentication bearer token to use when accessing the specified registry. For example:

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

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

🌐 You may also use an environment variable. For example:

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

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

🌐 Environment variables are only expanded in user-level auth files, not in the project-level .npmrc. See Environment variables in auth settings.

特定范围的认证令牌

🌐 Scope-specific auth tokens

新增于：v11.7.0

🌐 Added in: v11.7.0

pnpm 可以为不同的包作用域使用不同的身份验证令牌，即使这些作用域指向相同的注册表 URL。在身份验证密钥中，在注册表 URL 之后添加包作用域：

🌐 pnpm can use different auth tokens for different package scopes, even when those scopes point to the same registry URL. Add the package scope after the registry URL in the auth key:

@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）。

🌐 When installing or publishing @org-a/*, pnpm uses ORG_A_TOKEN; for @org-b/*, it uses ORG_B_TOKEN. Optionally, packages without a matching scope fall back to the registry-wide token (FALLBACK_TOKEN above), when provided.

pnpm login --registry=https://npm.pkg.github.com --scope=@org-a 将令牌写入相同的特定范围的认证密钥。

这对于每个组织或每个范围发放令牌的注册表（例如 GitHub Packages）非常有用。以前，身份验证仅通过注册表 URL 选择，因此共享同一注册表的两个范围必须共享一个令牌。

🌐 This is useful for registries (such as GitHub Packages) that issue tokens per organization or per scope. Previously, auth was selected only by registry URL, so two scopes sharing a registry had to share a token.

<URL>:tokenHelper

令牌助手是一个可执行程序，用于输出认证令牌。在认证令牌不是固定值而是定期刷新的情况下，可以使用它，脚本或其他工具可以使用现有的刷新令牌来获取新的访问令牌。

🌐 A token helper is an executable which outputs an auth token. This can be used in situations where the authToken is not a constant value but is something that refreshes regularly, where a script or other tool can use an existing refresh token to obtain a new access token.

辅助程序路径的配置必须是绝对路径，并且不能带有参数。为了安全起见，只允许在用户 .npmrc 中设置此值。否则，一个项目可能会在项目的本地 .npmrc 中设置一个值并运行任意可执行程序。

🌐 The configuration for the path to the helper must be an absolute path, with no arguments. In order to be secure, it is only permitted to set this value in the user .npmrc. Otherwise a project could place a value in a project's local .npmrc and run arbitrary executables.

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

🌐 Setting a token helper for the default registry:

tokenHelper=/home/ivan/token-generator

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

🌐 Setting a token helper for the specified registry:

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

_auth

新增于：v11.10.0

🌐 Added in: v11.10.0

将注册表身份验证配置为单个结构化值，以注册表 URL 作为键。这是对许多 //host/:_authToken=… 条目的替代方案，旨在用于 CI，其中基于 URL 的形式（其变量名包含 /、: 和 .）在某些运行器上无法通过环境变量传递。

🌐 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 仅从两个受信任的位置被授权：

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

它在项目 pnpm-workspace.yaml 或 .npmrc 中被忽略，因此签出的仓库永远无法提供注册表认证。

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

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

🌐 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.

在全球 config.yaml 中：

🌐 In the global config.yaml:

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

等效的环境变量（一个 JSON 字符串）:

🌐 The equivalent environment variable (a JSON string):

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

pnpm_config__auth（小写）和 PNPM_CONFIG__AUTH（全大写，一些 CI 运行器采用的约定）都会被认可。如果两者都设置了，小写优先，除非小写为空，此时使用大写。

🌐 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.

每个条目还推断出一个受信任的注册表路径：@ 路由默认注册表（并且 pnpm add <pkg> 在那里解析），而 @org 路由该作用域。因为凭证及其目标主机以一个受信任的值到达，所以由仓库控制的配置无法将令牌重定向到不同的主机。

🌐 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:

命令行标志（--registry、--@scope:registry）
pnpm_config__auth / PNPM_CONFIG__AUTH
全局 config.yaml _auth
pnpm-workspace.yaml

解析是严格的：格式错误的值（错误的 JSON、错误的结构、无效的注册表 URL 或作用域，或不支持的凭证字段）会立即报错，而不是被悄悄丢弃。

🌐 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.

证书设置

🌐 Certificate Settings

ca

默认：npm CA 证书
类型：字符串、数组或空

用于注册表的 SSL 连接的受信任证书颁发机构签名证书。值应为 PEM 格式（也称为“Base-64 编码的 X.509 (.CER)”）。例如：

🌐 The Certificate Authority signing certificate that is trusted for SSL connections to the registry. Values should be in PEM format (AKA "Base-64 encoded X.509 (.CER)"). For example:

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

设置为 null 以仅允许已知的注册商，或设置为特定的 CA 证书以仅信任该特定的签名机构。

🌐 Set to null to only allow known registrars, or to a specific CA cert to trust only that specific signing authority.

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

🌐 Multiple CAs can be trusted by specifying an array of certificates:

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

另请参见 strictSsl 设置。

🌐 See also the strictSsl setting.

cafile

默认：空
类型：路径

指向包含一个或多个证书颁发机构签名证书的文件的路径。类似于 ca 设置，但允许多个 CA，以及 CA 信息存储在文件中，而不是通过命令行指定。

🌐 A path to a file containing one or multiple Certificate Authority signing certificates. Similar to the ca setting, but allows for multiple CAs, as well as for the CA information to be stored in a file instead of being specified via CLI.

<URL>:cafile

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

🌐 Define the path to a Certificate Authority file to use when accessing the specified registry. For example:

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

<URL>:ca

新增于：v10.25.0

🌐 Added in: v10.25.0

为指定的注册表定义一个内联证书颁发机构(CA)证书。该值必须是PEM编码的，类似于全局的 ca 设置，但它仅适用于匹配的注册表URL。

🌐 Define an inline Certificate Authority certificate for the specified registry. The value must be PEM-encoded, like the global ca setting, but it only applies to the matching registry URL.

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

cert

默认：空
类型：字符串

访问注册表时需要传递的客户端证书。值应为 PEM 格式（也称“Base-64 编码的 X.509 (.CER)”）。例如：

🌐 A client certificate to pass when accessing the registry. Values should be in PEM format (AKA "Base-64 encoded X.509 (.CER)"). For example:

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

它不是证书文件的路径。

🌐 It is not the path to a certificate file.

<URL>:cert

新增于：v10.25.0

🌐 Added in: v10.25.0

定义在访问指定注册表时使用的内联客户端证书。示例：

🌐 Define an inline client certificate to use when accessing the specified registry. Example:

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

<URL>:certfile

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

🌐 Define the path to a certificate file to use when accessing the specified registry. For example:

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

key

默认：空
类型：字符串

访问注册表时需要传递的客户端密钥。值应采用 PEM 格式（即“Base-64 编码的 X.509 (.CER)”）。例如：

🌐 A client key to pass when accessing the registry. Values should be in PEM format (AKA "Base-64 encoded X.509 (.CER)"). For example:

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

这不是密钥文件的路径。如果需要引用文件系统而不是内联密钥，请使用 <URL>:keyfile。

🌐 It is not the path to a key file. Use <URL>:keyfile if you need to reference the file system instead of inlining the key.

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

🌐 This setting contains sensitive information. Don't write it to a local .npmrc file committed to the repository.

<URL>:key

新增于：v10.25.0

🌐 Added in: v10.25.0

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

🌐 Define an inline client key for the specified registry URL.

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

<URL>:keyfile

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

🌐 Define the path to a client key file to use when accessing the specified registry. For example:

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

认证文件位置​

认证设置中的环境变量​

身份验证设置​

<URL>:_authToken​

特定范围的认证令牌​

<URL>:tokenHelper​

_auth​

证书设置​

ca​

cafile​

<URL>:cafile​

<URL>:ca​

cert​

<URL>:cert​

<URL>:certfile​

key​

<URL>:key​

<URL>:keyfile​

认证文件位置

认证设置中的环境变量

身份验证设置

<URL>:_authToken

特定范围的认证令牌

<URL>:tokenHelper

_auth

证书设置

ca

cafile

<URL>:cafile

<URL>:ca

cert

<URL>:cert

<URL>:certfile

key

<URL>:key

<URL>:keyfile