认证设置

This page covers registry credentials and client certificates. These settings hold secrets. Keep them out of your repository.

For other settings, such as proxies and registries, see Settings (pnpm-workspace.yaml).

Quick start#

On your machine, log in to the registry:

pnpm login

pnpm saves the token in <pnpm config>/auth.ini. See Auth file locations.

In CI, pass the token through an environment variable:

export pnpm_config__auth='{"https://registry.npmjs.org":{"@":{"authToken":"${NPM_TOKEN}"}}}'

认证文件位置#

pnpm reads auth settings from two kinds of files.

INI files in npm's .npmrc format hold the .npmrc and auth.ini settings and the certificate settings. If a key is set in more than one file, the first file in this list wins:

1. <workspace root>/.npmrc, the project file. Add it to .gitignore.
2. <pnpm config>/auth.ini. pnpm login and pnpm config set write auth keys here.
3. ~/.npmrc, so credentials you set up for npm keep working. To read a different file, use the npmrcAuthFile setting.

The global <pnpm config>/config.yaml can hold the _auth setting.

<pnpm config> 目录是：

• $XDG_CONFIG_HOME/pnpm/, if XDG_CONFIG_HOME is set
• ~/AppData/Local/pnpm/config/ on Windows
• ~/Library/Preferences/pnpm/ on macOS
• ~/.config/pnpm/ on Linux

Settings in .npmrc and auth.ini#

Set these in one of the INI files listed in Auth file locations.

<URL>:_authToken#

The bearer token for a registry:

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

In a user-level auth file, the value can reference an environment variable:

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

请参阅 身份验证设置中的环境变量。

特定作用域的认证令牌#

Some registries, such as GitHub Packages, issue a separate token for each scope. Put the scope after the registry URL in the 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

pnpm sends ORG_A_TOKEN for @org-a/* packages and ORG_B_TOKEN for @org-b/* packages. Other packages from that registry get FALLBACK_TOKEN, if it is set.

pnpm login --registry=https://npm.pkg.github.com --scope=@org-a saves the token under the same scoped key.

<URL>:tokenHelper#

The path to a program that prints a token. Use it for tokens that expire, so a script can fetch a fresh one.

pnpm runs the program and sends its output as Authorization: Bearer <output>. If the output already starts with a word and a space, such as Bearer abc, Basic abc, or Token abc, pnpm sends it unchanged.

The path must be absolute and take no arguments. pnpm reads tokenHelper only from user-level auth files. A project .npmrc could otherwise make pnpm run any program. Environment variables cannot set it either.

For the default registry:

tokenHelper=/home/ivan/token-generator

For a specific registry:

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

Settings in config.yaml#

_auth#

All registry tokens in one value, keyed by registry URL. Use it in CI, where the //host/:_authToken key cannot be an environment variable name on some runners.

pnpm reads _auth from two places only:

• the global config.yaml
• the pnpm_config__auth environment variable, as JSON

pnpm ignores _auth in pnpm-workspace.yaml and .npmrc.

在全局 config.yaml 中：

_auth:
  https://registry.npmjs.org:
    "@":
      authToken: npm-token
    "@org":
      authToken: org-token

The same value as an environment variable:

export pnpm_config__auth='{"https://registry.npmjs.org":{"@":{"authToken":"npm-token"},"@org":{"authToken":"org-token"}}}'

pnpm also reads PNPM_CONFIG__AUTH, the all-caps name some CI runners use. If both are set, the lowercase one wins unless it is empty.

The value follows these rules:

• Each top-level key is an http or https registry URL, with no credentials, query string, or fragment.
• Under a URL, "@" holds the token for the whole registry. "@org" holds the token for packages in the @org scope.
• authToken is the only credential field. It is a bearer token.
• authToken can reference an environment variable as ${NAME}.

Each entry also routes packages to its URL. "@" makes the URL the default registry, and "@org" sends @org/* packages there. This routing has the following priority, highest first:

1. --registry and --@scope:registry on the command line
2. pnpm_config__auth or PNPM_CONFIG__AUTH
3. _auth in the global config.yaml
4. pnpm-workspace.yaml

认证设置中的环境变量#

User-level auth files, <pnpm config>/auth.ini and ~/.npmrc, can reference environment variables as ${NAME}:

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

npm's ${NAME?} form works too. It expands to an empty string when NAME is unset, without a warning. If an empty variable removes an auth token, pnpm prints a warning that names the key.

pnpm does not expand environment variables in the project .npmrc for:

• registry and proxy URLs: registry, @scope:registry, proxy, https-proxy, http-proxy
• keys that start with //
• credentials: _authToken, _auth, _password, username, tokenHelper, cert, key

pnpm ignores such a setting and prints a warning. The project .npmrc comes with the repository, so a malicious repository could otherwise send your CI tokens to a registry it controls (GHSA-3qhv-2rgh-x77r).

Moving a token out of the project .npmrc#

If your repository commits a line such as //registry.npmjs.org/:_authToken=${NPM_TOKEN}, use one of these instead.

Pass the token in an environment variable named after the key:

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

Shells cannot export this name, because it contains /, :, and .. Use env as above, or set the variable in your CI provider's settings. It overrides the project .npmrc, and a command-line option overrides it.

Or use _auth, as in the quick start.

Or save the token in <pnpm config>/auth.ini in a CI step:

pnpm config set //registry.npmjs.org/:_authToken "$NPM_TOKEN"

Or move the ${NPM_TOKEN} line to ~/.npmrc, or to the file that npmrcAuthFile names.

In GitHub Actions, actions/setup-node with the registry-url input already works. It writes a user-level .npmrc and points NPM_CONFIG_USERCONFIG at it. pnpm reads that file, so NODE_AUTH_TOKEN keeps working.

If you cannot change every CI pipeline, mark the project .npmrc as trusted with one variable in the CI environment:

PNPM_CONFIG_NPMRC_AUTH_FILE=.npmrc

This sets npmrcAuthFile. pnpm then reads the project .npmrc as the user-level auth file and expands its variables. A relative path is resolved against the working directory. A repository cannot set this variable, because it comes from the environment. pnpm also reads npm's NPM_CONFIG_USERCONFIG if this variable is unset.

The same applies to a registry URL built from an environment variable. Move it to ~/.npmrc or set it with pnpm config set "<key>" <value>. A URL that is not secret can be written out in the project .npmrc. For registries in pnpm-workspace.yaml, see registries.

Certificate settings#

Like the token settings, these go in .npmrc or auth.ini.

ca#

• Default: null (the CA certificates bundled with Node.js)
• 类型：String，Array 或 null

The certificate authority (CA) certificate to trust for TLS connections to the registry, in PEM format:

ca="-----BEGIN CERTIFICATE-----\nXXXX\nXXXX\n-----END CERTIFICATE-----"

To trust several CAs, use an array:

ca[]="..."
ca[]="..."

Set it to null to trust only the well-known CAs.

See also strictSsl.

cafile#

• 默认值： null
• 类型：路径

The path to a file with one or more CA certificates. Use it instead of ca to keep the certificates in a file.

<URL>:ca#

A CA certificate in PEM format, trusted only for the given registry:

//registry.example.com/:ca=-----BEGIN CERTIFICATE-----...-----END CERTIFICATE-----

<URL>:CA文件#

The path to a CA certificate file for the given registry:

//registry.npmjs.org/:cafile=ca-cert.pem

cert#

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

The client certificate to send to the registry, in PEM format. The value is the certificate itself, not a path:

cert="-----BEGIN CERTIFICATE-----\nXXXX\nXXXX\n-----END CERTIFICATE-----"

<URL>:cert#

The client certificate to send to the given registry:

//registry.example.com/:cert=-----BEGIN CERTIFICATE-----...-----END CERTIFICATE-----

<URL>:证书文件#

The path to a client certificate file for the given registry:

//registry.npmjs.org/:certfile=server-cert.pem

key#

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

The client key to send to the registry, in PEM format. The value is the key itself, not a path. To read the key from a file, use <URL>:keyfile.

key="-----BEGIN PRIVATE KEY-----\nXXXX\nXXXX\n-----END PRIVATE KEY-----"

<URL>:key#

The client key for the given registry:

//registry.example.com/:key=-----BEGIN PRIVATE KEY-----...-----END PRIVATE KEY-----

<URL>:密钥文件#

The path to a client key file for the given registry:

//registry.npmjs.org/:keyfile=server-key.pem