Skip to main content
Version: 10.x

认证与仓库设置 (.npmrc)

此页面上的设置必须通过 .npmrc 文件进行配置。pnpm 在发布时会在底层使用 npm CLI，因此这些设置需要采用 npm 可以读取的格式。

🌐 The settings on this page must be configured via .npmrc files. pnpm uses the npm CLI under the hood for publishing, so these settings need to be in a format that npm can read.

有关 .npmrc 文件加载方式的详细信息，请参阅 pnpm config 命令。

🌐 For details on how .npmrc files are loaded, see the pnpm config command.

有关可以在 pnpm-workspace.yaml 中配置的设置，请参阅 设置 (pnpm-workspace.yaml)。

🌐 For settings that can be configured in pnpm-workspace.yaml, see Settings (pnpm-workspace.yaml).

环境变量​

🌐 Environment variables

.npmrc 文件中的值可能使用 ${NAME} 语法引用环境变量。

🌐 Values in .npmrc files may reference environment variables using the ${NAME} syntax.

从 v10.34.2 起，环境变量在项目和工作区 .npmrc 文件（随仓库一起签出的文件）中的以下设置不会被展开：

🌐 Since v10.34.2, environment variables are not expanded in the project and workspace .npmrc files (those checked out together with the repository) for the following settings:

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

如果某个设置在任何这些位置包含 ${...} 占位符，该设置将被忽略，并且 pnpm 会打印警告。受仓库控制的 .npmrc 文件不得能够将环境变量扩展到 pnpm 发送请求的 URL 中，或附加到这些请求的凭据中——否则恶意仓库可能在安装过程中将你的环境中的秘密（例如 CI 令牌）泄露给攻击者控制的注册表 (GHSA-3qhv-2rgh-x77r)。

🌐 A setting that contains a ${...} placeholder in any of these positions is ignored, and pnpm prints a warning. Repository-controlled .npmrc files must not be able to expand environment variables into the URLs pnpm sends requests to, or into the credentials attached to those requests — otherwise a malicious repository could 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 默认写入全局配置文件，而不是项目 .npmrc，所以令牌从未出现在仓库中。

  • 或者保留 ${NPM_TOKEN} 占位符行，但将其放在用户级别的 ~/.npmrc 中，而不是仓库中 —— 环境变量在那里仍然会被展开。

  • 或者直接通过环境变量设置值，而不需要任何 .npmrc 条目：

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

  • 在 GitHub Actions 中，带有 registry-url 输入的 actions/setup-node 会将身份验证设置写入用户级别的 .npmrc（由 NPM_CONFIG_USERCONFIG 环境变量引用，pnpm 会使用它），因此通过 NODE_AUTH_TOKEN 环境变量进行的身份验证仍然有效。

  • 如果你无法轻松修改每个 CI 流水线，你可以通过在 CI 环境中设置单个环境变量（例如，在组织或工作区级别）来声明项目 .npmrc 是受信任的：

    NPM_CONFIG_USERCONFIG=.npmrc

    这使得 pnpm 将项目的 .npmrc 读取为用户级配置文件（相对路径会相对于工作目录解析），因此其中的环境变量会像以前一样被展开。因为信任声明来自环境 —— 而不是来自仓库 —— 恶意仓库无法为你设置它。

    danger

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

同样的规则适用于项目或工作区 .npmrc (registry, @scope:registry, proxy, https-proxy, http-proxy) 中的 注册表和代理 URL。如果你使用环境变量构建了注册表 URL，请将设置移到受信任的来源——你的用户级 ~/.npmrc、全局配置 (pnpm config set "<key>" <value>)、CLI 选项或环境变量。如果 URL 不是秘密，你也可以直接将解析后的值写入项目 .npmrc，因为只有 ${...} 占位符会被忽略。

注册表设置​

🌐 Registry Settings

registry​

npm 包注册表的基本 URL（包括尾部斜杠）。

🌐 The base URL of the npm package registry (trailing slash included).

@jsr:registry​

新增于：v10.9.0

🌐 Added in: v10.9.0

JSR 包注册表的基础 URL。

🌐 The base URL of the JSR package registry.

<scope>:registry​

应当用于指定范围包的 npm 注册表。例如，设置 @babel:registry=https://example.com/packages/npm/ 将强制在使用 pnpm add @babel/core 或任何 @babel 范围的包时，从 https://example.com/packages/npm 获取包，而不是从默认注册表获取。

🌐 The npm registry that should be used for packages of the specified scope. For example, setting @babel:registry=https://example.com/packages/npm/ will enforce that when you use pnpm add @babel/core, or any @babel scoped package, the package will be fetched from https://example.com/packages/npm instead of the default registry.

身份验证设置​

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

自 v10.34.2 起，环境变量仅在受信任的位置展开（用户 ~/.npmrc、全局配置、CLI 选项和 npm_config_* 环境变量），而不会在项目或工作区 .npmrc 中展开。请参阅 环境变量。

🌐 Since v10.34.2, environment variables are only expanded in trusted locations (the user ~/.npmrc, the global config, CLI options, and npm_config_* environment variables), not in the project or workspace .npmrc. See Environment variables.

或者你也可以直接使用环境变量，而完全不改变 .npmrc ：

🌐 Or you may just use an environment variable directly, without changing .npmrc at all:

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

<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

代理设置​

🌐 Proxy Settings

https-proxy​

  • 默认：空
  • 类型：网址

用于传出 HTTPS 请求的代理。如果设置了 HTTPS_PROXY、https_proxy、HTTP_PROXY 或 http_proxy 环境变量，将使用它们的值。

🌐 A proxy to use for outgoing HTTPS requests. If the HTTPS_PROXY, https_proxy, HTTP_PROXY or http_proxy environment variables are set, their values will be used instead.

如果你的代理URL包含用户名和密码，务必对它们进行网址编码。 例如：

🌐 If your proxy URL contains a username and password, make sure to URL-encode them. For instance:

https-proxy=https://use%21r:pas%2As@my.proxy:1234/foo

不要对用户名和密码之间的冒号（:）进行编码。

🌐 Do not encode the colon (:) between the username and password.

http-proxy​

proxy​

  • 默认：空
  • 类型：网址

用于外发 HTTP 请求的代理。如果设置了 HTTP_PROXY 或 http_proxy 环境变量，则底层请求库将遵循代理设置。

🌐 A proxy to use for outgoing http requests. If the HTTP_PROXY or http_proxy environment variables are set, proxy settings will be honored by the underlying request library.

local-address​

  • 默认：未定义
  • 类型：IP地址

在连接到 npm 注册表时要使用的本地接口的 IP 地址。

🌐 The IP address of the local interface to use when making connections to the npm registry.

maxsockets​

  • 默认值：networkConcurrency x 3
  • 类型：数字

每个源使用的最大连接数（协议/主机/端口组合）。

🌐 The maximum number of connections to use per origin (protocol/host/port combination).

noproxy​

  • 默认：空
  • 类型：字符串

不应使用代理的以逗号分隔的域扩展字符串。

🌐 A comma-separated string of domain extensions that a proxy should not be used for.

SSL 设置​

🌐 SSL Settings

strict-ssl​

  • 默认：真
  • 类型：布尔

在通过 HTTPS 向注册表发出请求时是否进行 SSL 密钥验证。

🌐 Whether or not to do SSL key validation when making requests to the registry via HTTPS.

另请参阅 ca 选项。

🌐 See also the ca option.

证书设置​

🌐 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[]="..."

另请参阅 strict-ssl 配置。

🌐 See also the strict-ssl config.

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>&#58;keyfile。

🌐 It is not the path to a key file. Use <URL>&#58;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