跳到主内容
版本：10.x

身份验证 & 注册源设置 (.npmrc)

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

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

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

环境变量​

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

自 v10.34.2 版本起，对于以下设置，项目和工作区 .npmrc 文件（即随仓库一同检出的文件）中的环境变量将不再进行展开：

  • 注册源和代理 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)。

如果你的项目依赖于一个已提交到版本控制系统的 .npmrc 文件，且其中包含类似 //registry.npmjs.org/:_authToken=${NPM_TOKEN} 的行，请务必将该令牌移至一个安全可靠的位置：

  • 在安装之前（例如在 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 文件作为用户级配置文件来读取（其中的相对路径会基于工作目录进行解析），因此其中的环境变量会像以前一样被展开。 由于信任声明来自环境而非仓库，恶意仓库无法代你进行此设置。

    警告

    仅在专门构建受信任仓库的环境中使用此设置。 它完全禁用了针对该检出仓库的此项保护，包括关于 tokenHelper 仅可在用户级配置中设置的限制。

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

注册源设置​

注册源​

npm 包注册源地址 (包括末尾斜杠) 。

@jsr:registry​

添加于：v10.9.0

JSR 包注册源的基础网址。

<scope>:registry​

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

认证设置​

<URL>:_authToken​

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

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

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

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

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

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

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

<URL>:tokenHelper​

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

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

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

tokenHelper=/home/ivan/token-generator

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

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

代理设置​

https-proxy​

  • 默认值： null
  • 类型：url

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

如果你的代理 URL 包含用户名和密码，请确保对它们进行 URL 编码。 例如：

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

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

http-proxy​

proxy​

  • 默认值： null
  • 类型：url

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

local-address​

  • 默认值：undefined
  • 类型：IP 地址

与 npm 注册源建立连接时要使用的本地接口的 IP 地址。

maxsockets​

  • 默认值：网络并发 x 3
  • 类型：Number

每个源(由协议/主机/端口号组合而成)允许的最大连接数。

noproxy​

  • 默认值： null
  • 类型：字符串

一个由逗号分割的域名字符串，表示不应该被使用的代理

SSL 设置​

strict-ssl​

  • 默认值：true
  • 类型：Boolean

通过 HTTPS 向registry发出请求时是否进行 SSL 密钥验证。

另请参阅 ca 配置项。

证书设置​

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

更多信息可见 strict-ssl 设置

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