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

    export "pnpm_config_//registry.npmjs.org/:_authToken=$NPM_TOKEN"

    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.

Scope-specific auth tokens​

Added in: v11.7.0

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

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​

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

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

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

tokenHelper=/home/ivan/token-generator

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

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

证书设置​

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