发布 Node.js 包

您可以在持续集成 (CI) 工作流的一部分中将 Node.js 包发布到注册表。

本文内容

简介

本指南向您展示如何创建一个工作流，在持续集成 (CI) 测试通过后将 Node.js 包发布到 GitHub Packages 和 npm 注册表。

先决条件

我们建议您对工作流配置选项以及如何创建工作流文件有基本的了解。有关详细信息，请参阅“编写工作流”。

有关为您的 Node.js 项目创建 CI 工作流的更多信息，请参阅“构建和测试 Node.js”。

您可能还会发现了解以下内容很有帮助

关于包配置

package.json 文件中的 name 和 version 字段创建了一个唯一的标识符，注册表使用该标识符将您的包链接到注册表。您可以通过在 package.json 文件中包含 description 字段来为包列表页面添加摘要。有关更多信息，请参阅 npm 文档中的“创建 package.json 文件”和“创建 Node.js 模块”。

当本地 .npmrc 文件存在并指定了 registry 值时，npm publish 命令将使用 .npmrc 文件中配置的注册表。您可以使用 setup-node 操作在运行程序上创建一个本地 .npmrc 文件，该文件配置默认注册表和作用域。setup-node 操作还接受身份验证令牌作为输入，用于访问私有注册表或发布节点包。有关更多信息，请参阅 setup-node。

您可以使用 setup-node 操作指定在运行程序上安装的 Node.js 版本。

如果您在工作流中添加步骤来配置 package.json 文件中的 publishConfig 字段，则无需使用 setup-node 操作指定 registry-url，但您将仅限于将包发布到一个注册表。有关更多信息，请参阅 npm 文档中的“publishConfig”。

将包发布到 npm 注册表

每次发布新版本时，您都可以触发工作流以发布您的包。以下示例中的过程在类型为 published 的发布事件触发时执行。如果 CI 测试通过，则该过程会将包上传到 npm 注册表。有关更多信息，请参阅“管理存储库中的版本”。

要在工作流中对 npm 注册表执行经过身份验证的操作，您需要将 npm 身份验证令牌存储为密钥。例如，创建一个名为 NPM_TOKEN 的存储库密钥。有关更多信息，请参阅“在 GitHub Actions 中使用密钥”。

默认情况下，npm 使用 package.json 文件的 name 字段来确定已发布包的名称。发布到全局命名空间时，您只需要包含包名称。例如，您将名为 my-package 的包发布到 https://npmjs.net.cn/package/my-package。

如果您发布的包包含作用域前缀，请在 package.json 文件的名称中包含该作用域。例如，如果您的 npm 作用域前缀为“octocat”且包名为“hello-world”，则 package.json 文件中的 name 应为 @octocat/hello-world。如果您的 npm 包使用作用域前缀且包为公共包，则需要使用选项 npm publish --access public。这是 npm 为了防止意外发布私有包而要求的一个选项。

如果您希望发布具有来源的包，请在您的 npm publish 命令中包含 --provenance 标志。这使您能够公开且可验证地建立包的构建位置和方式，从而提高使用您包的人员的供应链安全性。有关更多信息，请参阅 npm 文档中的生成来源声明。

此示例将 NPM_TOKEN 密钥存储在 NODE_AUTH_TOKEN 环境变量中。当 setup-node 操作创建 .npmrc 文件时，它会从 NODE_AUTH_TOKEN 环境变量引用该令牌。

YAML
name: Publish Package to npmjs
on:
  release:
    types: [published]
jobs:
  build:
    runs-on: ubuntu-latest
    permissions:
      contents: read
      id-token: write
    steps:
      - uses: actions/checkout@v4
      # Setup .npmrc file to publish to npm
      - uses: actions/setup-node@v4
        with:
          node-version: '20.x'
          registry-url: 'https://registry.npmjs.org'
      - run: npm ci
      - run: npm publish --provenance --access public
        env:
          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}

在上面的示例中，setup-node 操作在运行程序上创建了一个 .npmrc 文件，其内容如下

//registry.npmjs.org/:_authToken=${NODE_AUTH_TOKEN}
registry=https://registry.npmjs.org/
always-auth=true

请注意，您需要将 registry-url 设置为 https://registry.npmjs.org/ 以在 setup-node 中正确配置您的凭据。

将包发布到 GitHub Packages

每次发布新版本时，您都可以触发工作流以发布您的包。以下示例中的过程在类型为 published 的发布事件触发时执行。如果 CI 测试通过，则该过程会将包上传到 GitHub Packages。有关更多信息，请参阅“管理存储库中的版本”。

配置目标存储库

使用 repository 键将您的包链接到 GitHub Packages 是可选的。如果您选择不在 package.json 文件中提供 repository 键，则发布包时不会将其链接到存储库，但您可以选择稍后将包连接到存储库。

如果您确实在 package.json 文件中提供了 repository 键，则该键中的存储库将用作 GitHub Packages 的目标 npm 注册表。例如，发布以下 package.json 会导致名为 my-package 的包发布到 octocat/my-other-repo GitHub 存储库。

{
  "name": "@octocat/my-package",
  "repository": {
    "type": "git",
    "url": "https://github.com/octocat/my-other-repo.git"
  },

对目标存储库进行身份验证

要在工作流中对 GitHub Packages 注册表执行经过身份验证的操作，您可以使用 GITHUB_TOKEN。每次工作流中的作业开始时，GITHUB_TOKEN 密钥都会设置为存储库的访问令牌。您应在工作流文件中设置此访问令牌的权限，以授予 contents 权限的读取访问权限和 packages 权限的写入访问权限。有关更多信息，请参阅“自动令牌身份验证”。

如果您想将包发布到其他存储库，则必须使用具有权限在目标存储库中写入包的个人访问令牌（经典）。有关更多信息，请参阅“管理您的个人访问令牌”和“在 GitHub Actions 中使用密钥”。

工作流示例

此示例将 GITHUB_TOKEN 密钥存储在 NODE_AUTH_TOKEN 环境变量中。当 setup-node 操作创建 .npmrc 文件时，它会从 NODE_AUTH_TOKEN 环境变量引用该令牌。

YAML
name: Publish package to GitHub Packages
on:
  release:
    types: [published]
jobs:
  build:
    runs-on: ubuntu-latest
    permissions:
      contents: read
      packages: write
    steps:
      - uses: actions/checkout@v4
      # Setup .npmrc file to publish to GitHub Packages
      - uses: actions/setup-node@v4
        with:
          node-version: '20.x'
          registry-url: 'https://npm.pkg.github.com'
          # Defaults to the user or organization that owns the workflow file
          scope: '@octocat'
      - run: npm ci
      - run: npm publish
        env:
          NODE_AUTH_TOKEN: ${{ secrets.GITHUB_TOKEN }}

setup-node 操作在运行程序上创建了一个 .npmrc 文件。当您将 scope 输入用于 setup-node 操作时，.npmrc 文件将包含作用域前缀。默认情况下，setup-node 操作会将 .npmrc 文件中的作用域设置为包含该工作流文件的帐户。

//npm.pkg.github.com/:_authToken=${NODE_AUTH_TOKEN}
@octocat:registry=https://npm.pkg.github.com
always-auth=true

使用 Yarn 发布包

如果您使用 Yarn 包管理器，则可以使用 Yarn 安装和发布包。

YAML
name: Publish Package to npmjs
on:
  release:
    types: [published]
jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      # Setup .npmrc file to publish to npm
      - uses: actions/setup-node@v4
        with:
          node-version: '20.x'
          registry-url: 'https://registry.npmjs.org'
          # Defaults to the user or organization that owns the workflow file
          scope: '@octocat'
      - run: yarn
      - run: yarn npm publish // for Yarn version 1, use `yarn publish` instead
        env:
          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}

要在发布期间对注册表进行身份验证，请确保您的身份验证令牌也已在您的 yarnrc.yml 文件中定义。有关更多信息，请参阅 Yarn 文档中的设置文章。