npm 的可信发布软件包

受信任的发布允许你使用 OpenID Connect (OIDC) 认证直接从你的 CI/CD 工作流发布 npm 包，从而无需长期使用 npm 令牌。此功能实现了由开源安全基金会 (OpenSSF) 指定的 受信任发布者行业标准，并加入了一个不断扩展的生态系统，包括 PyPI、RubyGems 以及其他主要的软件包注册中心，提供这一安全增强功能。

🌐 Trusted publishing allows you to publish npm packages directly from your CI/CD workflows using OpenID Connect (OIDC) authentication, eliminating the need for long-lived npm tokens. This feature implements the trusted publishers industry standard specified by the Open Source Security Foundation (OpenSSF), joining a growing ecosystem including PyPI, RubyGems, and other major package registries in offering this security enhancement.

可信发布的工作原理

🌐 How trusted publishing works

受信任的发布通过 OIDC 在 npm 与你的 CI/CD 提供商之间创建信任关系。当你为你的包配置受信任的发布者时，npm 将接受你授权的特定工作流的发布，除此之外，还可以使用 npm 令牌和手动发布等传统身份验证方法。npm CLI 会自动检测 OIDC 环境，并在回退到传统令牌之前使用它们进行身份验证。

🌐 Trusted publishing creates a trust relationship between npm and your CI/CD provider using OIDC. When you configure a trusted publisher for your package, npm will accept publishes from the specific workflow you've authorized, in addition to traditional authentication methods like npm tokens and manual publishes. The npm CLI automatically detects OIDC environments and uses them for authentication before falling back to traditional tokens.

这种方法消除了与长期有效的写入令牌相关的安全风险，这些令牌可能被泄露、意外记录在日志中，或需要手动轮换。相反，每次发布都使用短期、加密签名的令牌，这些令牌特定于你的工作流程，无法被提取或重复使用。

🌐 This approach eliminates the security risks associated with long-lived write tokens, which can be compromised, accidentally exposed in logs, or require manual rotation. Instead, each publish uses short-lived, cryptographically-signed tokens that are specific to your workflow and cannot be extracted or reused.

支持的 CI/CD 提供商

🌐 Supported CI/CD providers

受信任的发布目前支持：

🌐 Trusted publishing currently supports:

• GitHub Actions（GitHub 托管的运行器）
• GitLab CI/CD 流水线（GitLab.com 共享运行器）

目前不支持自托管运行器，但计划在未来版本中支持。

🌐 Self-hosted runners are not currently supported but are planned for future releases.

配置可信发布

🌐 Configuring trusted publishing

步骤 1：在 npmjs.com 上添加受信任的发布者

🌐 Step 1: Add a trusted publisher on npmjs.com

导航到 npmjs.com 上的包设置，找到“可信发布者”部分。在“选择你的发布者”下，点击 GitHub Actions 或 GitLab CI/CD 按钮，选择你的 CI/CD 提供商。

🌐 Navigate to your package settings on npmjs.com and find the "Trusted Publisher" section. Under "Select your publisher", choose your CI/CD provider by clicking either the GitHub Actions or GitLab CI/CD button.

对于 GitHub Actions

🌐 For GitHub Actions

配置以下字段：

🌐 Configure the following fields:

• 组织或用户（必填）：你的 GitHub 用户名或组织名称
• 仓库（必填）：你的仓库名称
• 工作流文件名（必填）：你的工作流文件名（例如，publish.yml）
  • 仅输入文件名，无需完整路径
  • 必须包含 .yml 或 .yaml 扩展名
  • 工作流文件必须存在于你仓库中的 .github/workflows/
• 环境名称（可选）：如果使用 GitHub 环境 进行部署保护

对于 GitLab CI/CD

🌐 For GitLab CI/CD

配置以下字段：

🌐 Configure the following fields:

• 命名空间（必填）：你的 GitLab 用户名或组名
• 项目名称（必填）：你的项目名称
• 顶层 CI 文件路径（必填）：你的 CI 文件路径（例如，.gitlab-ci.yml）
  • 必须包含 .yml 扩展名
• 环境名称（可选）：如果使用 GitLab 环境

步骤 2：配置你的 CI/CD 工作流

🌐 Step 2: Configure your CI/CD workflow

GitHub Actions 配置

🌐 GitHub Actions configuration

将所需的 OIDC 权限添加到你的工作流中。下面是一个完整的示例：

🌐 Add the required OIDC permissions to your workflow. Here's a complete example:

name: Publish Package

on:
  push:
    tags:
      - 'v*'

permissions:
  id-token: write  # Required for OIDC
  contents: read

jobs:
  publish:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - uses: actions/setup-node@v4
        with:
          node-version: '24'
          registry-url: 'https://registry.npmjs.org'
      - run: npm ci
      - run: npm run build --if-present
      - run: npm test
      - run: npm publish

关键要求是 id-token: write 权限，它允许 GitHub Actions 生成 OIDC 令牌。更多信息请参阅 GitHub 的 OIDC 文档。

🌐 The critical requirement is the id-token: write permission, which allows GitHub Actions to generate OIDC tokens. Learn more in GitHub's OIDC documentation.

GitLab CI/CD 配置

🌐 GitLab CI/CD configuration

在你的管道中配置 OIDC ID 令牌：

🌐 Configure the OIDC ID token in your pipeline:

stages:
  - test
  - build
  - publish

variables:
  NODE_VERSION: '24'

test:
  stage: test
  image: node:${NODE_VERSION}
  script:
    - npm ci
    - npm test

publish:
  stage: publish
  image: node:${NODE_VERSION}
  id_tokens:
    NPM_ID_TOKEN:
      aud: "npm:registry.npmjs.org"
    SIGSTORE_ID_TOKEN:
      aud: sigstore
  script:
    - npm ci
    - npm run build --if-present
    - npm publish
  only:
    - tags

id_tokens 配置告诉 GitLab 为 npm 生成 OIDC 令牌。详细信息请参阅 GitLab 的 OIDC 文档。

🌐 The id_tokens configuration tells GitLab to generate an OIDC token for npm. Learn more in GitLab's OIDC documentation.

管理可信发布者配置

🌐 Managing trusted publisher configurations

你可以随时通过 npmjs.com 上的软件包设置修改或删除你的受信任发布者配置。每个软件包一次只能有一个受信任发布者连接，但可以根据需要编辑或删除此连接。要更改提供商（例如，从 GitHub Actions 切换到 GitLab CI/CD），只需编辑现有配置并选择新的提供商。更改将在未来的发布中立即生效。要完全取消受信任发布，并恢复基于令牌的身份验证，请从你的软件包设置中删除受信任发布者配置。

🌐 You can modify or remove your trusted publisher configuration at any time through your package settings on npmjs.com. Each package can only have one trusted publisher connection at a time, but this connection can be edited or deleted as needed. To change providers (for example, switching from GitHub Actions to GitLab CI/CD), simply edit your existing configuration and select the new provider. The change takes effect immediately for future publishes. To remove trusted publishing entirely and return to token-based authentication, delete the trusted publisher configuration from your package settings.

建议：使用受信任的发布者时限制令牌访问

🌐 Recommended: Restrict token access when using trusted publishers

配置好软件包的受信任发布者后，我们强烈建议限制传统的基于令牌的发布访问权限，以增强安全性。

🌐 Once you've configured trusted publishers for your package, we strongly recommend restricting traditional token-based publishing access for enhanced security.

如何配置最高安全级别

🌐 How to configure maximum security

1. 启用受信任的发布者后，导航到你的包的 设置 → 发布访问
2. 选择 “要求双因素认证并禁止使用令牌”
3. 点击 更新包设置 保存你的更改

为什么选择此版本事项

🌐 Why this matters

受信任的发布者使用在你的 CI/CD 工作流中按需生成的短期作用域凭证，从而无需使用长期令牌。通过在使用受信任的发布者时限制传统令牌访问，你可以减少与凭证管理相关的潜在安全风险。

🌐 Trusted publishers use short-lived, scoped credentials that are generated on-demand during your CI/CD workflow, eliminating the need for long-lived tokens. By restricting traditional token access while using trusted publishers, you reduce potential security risks associated with credential management.

注意： “禁止令牌”设置仅影响传统令牌认证。受信任的发布者将继续正常工作，因为他们使用的是 OIDC 令牌。

迁移技巧

🌐 Migration tip

如果你正在从基于令牌的发布方式过渡：

🌐 If you're transitioning from token-based publishing:

1. 请先设置受信任的发布者并验证其是否正常工作
2. 然后按照上述说明限制令牌访问权限。
3. 撤销任何不再需要的现有自动化令牌

这可确保平稳过渡，不会中断你的发布流程。

🌐 This ensures a smooth transition without disrupting your release process.

自动溯源生成

🌐 Automatic provenance generation

当你使用受信任的发布方式进行发布时，npm 会自动为你的包生成并发布 源证明声明。这是默认行为——你无需在发布命令中添加 --provenance 标志。

🌐 When you publish using trusted publishing, npm automatically generates and publishes provenance attestations for your package. This happens by default—you don't need to add the --provenance flag to your publish command.

来源提供了关于你的软件包是在哪里以及如何构建的加密证明，使用户能够验证其真实性。只有当满足以下所有条件时，才会自动生成此证明：

🌐 Provenance provides cryptographic proof of where and how your package was built, allowing users to verify its authenticity. This automatic generation only applies when all of these conditions are met:

• 通过可信发布 (OIDC) 发布
• 从公共仓库发布
• 发布公共软件包

禁用溯源生成

🌐 Disabling provenance generation

虽然我们强烈建议保持来源跟踪功能启用，但如果需要，你可以将其禁用。在以下任意方式中将 provenance 选项设置为 false：

🌐 While we strongly recommend keeping provenance enabled, you can disable it if needed. Set the provenance option to false in any of these ways:

使用环境变量：

NPM_CONFIG_PROVENANCE=false npm publish

在你的 .npmrc 文件中：

provenance=false

在你的 package.json 中：

{
  "publishConfig": {
    "provenance": false
  }
}

安全最佳实践

🌐 Security best practices

优先使用可信发布而不是令牌

🌐 Prefer trusted publishing over tokens

当你的工作流程中可使用受信任的发布方式时，总是优先选择它，而不是使用长期有效的令牌。传统的 npm 令牌存在多种安全风险：

🌐 When trusted publishing is available for your workflow, always prefer it over long-lived tokens. Traditional npm tokens pose several security risks:

• 它们可能会在 CI 日志或配置文件中意外暴露
• 它们需要手动轮换和管理
• 如果遭到入侵，它们将提供持久访问权限，直至被撤销
• 它们通常具有比必要更广泛的权限

可信发布通过使用短期有效、特定于工作流的凭据来消除这些风险，这些凭据会自动管理且无法提取。

🌐 Trusted publishing eliminates these risks by using short-lived, workflow-specific credentials that are automatically managed and cannot be extracted.

处理私有依赖

🌐 Handling private dependencies

虽然受信任的发布系统会处理发布操作，但在安装私有 npm 依赖时，你仍可能需要进行身份验证。对于这种情况，我们建议：

🌐 While trusted publishing handles the publish operation, you may still need authentication for installing private npm dependencies. For this scenario, we recommend:

# GitHub Actions example
- uses: actions/setup-node@v4
  with:
    node-version: '24'
    registry-url: 'https://registry.npmjs.org'
# Use a read-only token for installing dependencies
- run: npm ci
  env:
    NODE_AUTH_TOKEN: ${{ secrets.NPM_READ_TOKEN }}

# Publish uses OIDC - no token needed
- run: npm publish

始终使用只读粒度访问令牌来安装依赖。如果令牌被泄露，这可以将潜在的损害降到最低。

🌐 Always use read-only granular access tokens for installing dependencies. This limits potential damage if the token is ever compromised.

其他安全措施

🌐 Additional security measures

请考虑实现以下额外的安全措施：

🌐 Consider implementing these additional security practices:

• 使用部署环境来添加审批要求
• 启用 标签保护规则 以控制谁可以创建发布标签
• 定期审核你的可信发布者配置
• 从你的 npm 账户中移除所有未使用的发布令牌

故障排除

🌐 Troubleshooting

如果在发布时遇到“无法认证”错误，请首先确认工作流文件名与你在 npmjs.com 上配置的名称完全一致，包括 .yml 扩展名。所有字段都区分大小写，必须完全匹配。同时，请确保你使用的是 GitHub 托管的运行器或 GitLab.com 共享运行器，因为当前不支持自托管运行器。对于 GitHub Actions，特别需要检查工作流中是否设置了 id-token: write 权限。

🌐 If you encounter an "Unable to authenticate" error when publishing, first verify that the workflow filename matches exactly what you configured on npmjs.com, including the .yml extension. All fields are case-sensitive and must be exact. Also ensure you're using GitHub-hosted runners or GitLab.com shared runners, as self-hosted runners are not currently supported. For GitHub Actions specifically, check that the id-token: write permission is set in your workflow.

如果你的包有私有依赖，并且 npm install 或 npm ci 出现身份验证错误，请记住，受信任的发布仅适用于 npm publish 命令。你仍然需要提供只读令牌来安装私有包，如上面的示例所示。

🌐 If your package has private dependencies and npm install or npm ci is failing with authentication errors, remember that trusted publishing only applies to the npm publish command. You'll still need to provide a read-only token for installing private packages as shown in the examples above.

对于私有仓库中的软件包，即使你使用受信任的发布，也不会生成来源信息。这是一个已知限制，无论你的软件包是公开的还是私有的，都适用。

🌐 For packages in private repositories, provenance will not be generated even though you're using trusted publishing. This is a known limitation that applies regardless of whether your package itself is public or private.

一些 GitHub Actions 工作流使用 workflow_call 来调用运行 npm publish 的其他工作流，或者使用 workflow_dispatch 进行手动发布。发生这种情况时，验证会检查调用工作流的名称，而不是实际包含发布命令的工作流，这可能导致配置不匹配。

🌐 Some GitHub Actions workflows use workflow_call to invoke other workflows that run npm publish, or use workflow_dispatch for manual publishing. When this happens, validation checks the calling workflow's name instead of the workflow that actually contains the publish command, which can cause configuration mismatches.

限制和未来改进

🌐 Limitations and future improvements

受信任的发布目前仅支持云托管运行器。对自托管运行器的支持计划在未来版本中提供。每个软件包一次只能配置一个受信任的发布者，但你可以根据需要更新此配置。

🌐 Trusted publishing currently supports only cloud-hosted runners. Support for self-hosted runners is intended for a future release. Each package can only have one trusted publisher configured at a time, though you can update this configuration as needed.

OIDC 认证目前仅限于发布操作。其他 npm 命令，如 install、view 或 access，仍然需要传统的认证方法。npm whoami 命令不会反映 OIDC 认证状态，因为认证仅在发布操作期间进行。

🌐 OIDC authentication is currently limited to the publish operation. Other npm commands such as install, view, or access still require traditional authentication methods. The npm whoami command will not reflect OIDC authentication status since the authentication occurs only during the publish operation.

我们计划将可信发布支持扩展到更多 CI/CD 提供商，并根据社区反馈增强该功能。

🌐 We intend to expand trusted publishing support to additional CI/CD providers and enhance the feature based on community feedback.

了解更多

🌐 Learn more

• 关于 npm 来源
• OpenSSF 受信任发布者规范
• GitHub Actions OIDC 文档
• GitLab CI/CD OIDC 文档
• 用于将 OIDC ID 令牌交换为 npm 注册表令牌的 API 文档