Skip to main content

发布 Node.js 包

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

注: GitHub 托管的运行器目前在 GitHub Enterprise Server 上不受支持。 您可以在 GitHub 公共路线图 上查看有关未来支持计划的更多信息。

简介

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

基本要求

建议基本了解工作流程配置选项和如何创建工作流程文件。 更多信息请参阅“Learn GitHub Actions”。

有关为 Node.js 项目创建 CI 工作流程的更多信息,请参阅“将 Node.js 与 GitHub Actions 一起使用。”

您可能还发现基本了解以下内容是有帮助的:

关于包配置

package.json 文件中的 nameversion 字段创建唯一标识符,供注册表用来将包链接到注册表。 您可以在 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 操作指定注册表 url,但软件包仅限于发布到一个注册表。 更多信息请参阅 npm 文档中的“publishConfig”。

发布包到 npm 注册表

每次创建新版本时,都可以触发工作流程来发布包。 以下示例中的工作流程在类型为 createdrelease 事件触发时运行。 如果 CI 测试通过,工作流程将包发布到 npm 注册表。

要根据工作流程中的 npm 注册表执行经过身份验证的操作,您需要将 npm 身份验证令牌作存储为密码。 例如,创建名为 NPM_TOKEN 的仓库密码。 更多信息请参阅“创建和使用加密密码”。

By default, npm uses the name field of the package.json file to determine the name of your published package. 当发布到全局命名空间时,您只需要包含包名称。 For example, you would publish a package named npm-hello-world-test to https://www.npmjs.com/package/npm-hello-world-test.

如果发布一个包含范围前缀的包,请将范围包含在 package.json 文件的名称中。 例如,如果 npm 范围前缀是 octocat 并且包名是 hello-world,则 package.json 文件中的 name 应为 @octocat/hello-world。 如果 npm 包使用范围前缀且包是公开的,则需使用选项 npm publish --access public。 这是 npm 需要用来防止有人无意中发布私有包的选项。

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

YAML
name: Publish Package to npmjs
on:
  release:
    types: [created]
jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v2
      # Setup .npmrc file to publish to npm
      - uses: actions/setup-node@v2
        with:
          node-version: '16.x'
          registry-url: 'https://registry.npmjs.org'
      - run: npm ci
      - run: npm publish
        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

Please note that you need to set the registry-url to https://registry.npmjs.org/ in setup-node to properly configure your credentials.

发布包到 GitHub Packages

每次创建新版本时,都可以触发工作流程来发布包。 以下示例中的工作流程在类型为 createdrelease 事件发生时运行。 如果 CI 测试通过,工作流程会将包发布到 GitHub Packages。

配置目标仓库

如果您没有在 package.json 文件中提供 repository 键,则 GitHub Packages 将包发布到您在 package.json 文件的 name 字段中指定的 GitHub 仓库。 例如,名为 @my-org/test 的包将被发布到 my-org/test GitHub 仓库。

但是,如果您提供了 repository 键,则该键中的仓库将被用作 GitHub Packages 的目标 npm 注册表。 例如,发布以下 package.json 将导致名为 my-amazing-package 的包被发布到 octocat/my-other-repo GitHub 仓库。

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

向目标仓库验证

要根据 GitHub Packages 注册表在工作流程中执行经验证的操作,可以使用 GITHUB_TOKEN。 每当工作流程中的作业开始时,都会将 GITHUB_TOKEN 密钥设置为仓库的访问令牌。 You should set the permissions for this access token in the workflow file to grant read access for the contents scope and write access for the packages scope. 更多信息请参阅“使用 GITHUB_TOKEN 验证身份”。

如果要将包发布到其他仓库,您必须使用对目标仓库中的包具有写入权限的个人访问令牌 (PAT)。 更多信息请参阅“创建个人访问令牌”和“加密密码”。

示例工作流程

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

YAML
name: Publish package to GitHub Packages
on:
  release:
    types: [created]
jobs:
  build:
    runs-on: ubuntu-latest 
    permissions: 
      contents: read
      packages: write 
    steps:
      - uses: actions/checkout@v2
      # Setup .npmrc file to publish to GitHub Packages
      - uses: actions/setup-node@v2
        with:
          node-version: '16.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: [created]
jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v2
      # Setup .npmrc file to publish to npm
      - uses: actions/setup-node@v2
        with:
          node-version: '16.x'
          registry-url: 'https://registry.npmjs.org'
          # Defaults to the user or organization that owns the workflow file
          scope: '@octocat'
      - run: yarn
      - run: yarn publish
        env:
          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}