跳到主内容
版本：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/

认证设置中的环境变量​

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}

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

  • registry and proxy URLs (registry, @scope:registry, proxy settings);
  • URL-scoped keys (keys starting with //);
  • credential values (_authToken, _auth, _password, username, tokenHelper, cert, key).

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

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 writes to the global location by default (<pnpm config>/auth.ini for auth settings), not to the project .npmrc, so the token never ends up in the repository.

  • Set the credential through an environment variable, with no .npmrc file at all (since v11.6). pnpm reads URL-scoped registry settings from pnpm_config_//… environment variables:

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

    The variable name contains /, :, and ., which export and the NAME=value shell assignment syntax reject as invalid identifiers. Use the env utility (as shown above) to pass it to a single command, or set it through a tool that accepts arbitrary variable names (for example, your CI provider's environment settings or Node's process.env).

    This is the most direct, file-free replacement for a committed //registry.npmjs.org/:_authToken=${NPM_TOKEN} line. 由于该凭证适用的注册源信息被编码在（受信任的）变量名中，恶意仓库无法将其重定向到其他主机。 Such an environment value overrides the project .npmrc but is itself overridden by a command-line option. The tokenHelper setting is intentionally not read from environment variables.

  • Or keep the ${NPM_TOKEN} placeholder line, but put it in the user-level ~/.npmrc (or the file referenced by npmrcAuthFile) instead of the repository.

  • In GitHub Actions, actions/setup-node with the registry-url input writes the auth setting to a user-level .npmrc (referenced by the NPM_CONFIG_USERCONFIG environment variable, which pnpm honors), so authentication via the NODE_AUTH_TOKEN environment variable continues to work.

  • If you cannot easily modify each CI pipeline, you may declare the project .npmrc trusted by setting a single environment variable in the CI environment (for example, at the organization or workspace level):

    PNPM_CONFIG_NPMRC_AUTH_FILE=.npmrc

    This is the env form of the npmrcAuthFile setting: it makes pnpm read the project's .npmrc as the user-level auth file (a relative path is resolved against the working directory), so environment variables in it are expanded as before. 由于信任声明来自环境而非仓库，恶意仓库无法代你进行此设置。 The npm-style NPM_CONFIG_USERCONFIG variable is also honored as a fallback.

    警告

    仅在专门构建受信任仓库的环境中使用此设置。 It disables this protection entirely for the checked-out repository, including the restriction that tokenHelper may only be set in user-level config.

The same rule applies to registry and proxy URLs in a project .npmrc (registry, @scope:registry, proxy, https-proxy, http-proxy). If you used an environment variable to build a registry URL, move the setting to a trusted source — your user-level ~/.npmrc, or pnpm config set "<key>" <value>. If the URL is not secret, you can also write the resolved value directly in the project .npmrc, since only ${...} placeholders are ignored. For registry settings in pnpm-workspace.yaml, see Settings.

认证设置​

<URL>:_authToken​

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

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

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

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

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

特定作用域的认证令牌​

添加于：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。 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 writes the token to the same scope-specific auth key.

这对按组织或范围发放令牌的注册源（如 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
  • 类型：路径

包含一个或多个 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