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

Environment variables in auth settings​

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:

  • Write the token to the user-level auth file before installing (for example, in a CI step):

    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.

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

认证设置​

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

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