简介
本指南介绍如何创建一个工作流程,以在持续集成 (CI) 测试通过后将 Node.js 包发布到 GitHub Packages 和 npm 注册表。
先决条件
建议基本了解工作流程配置选项和如何创建工作流程文件。 有关详细信息,请参阅“了解 GitHub Actions”。
有关为 Node.js 项目创建 CI 工作流的详细信息,请参阅“将 Node.js 与 GitHub Actions 配合使用。”
您可能还发现基本了解以下内容是有帮助的:
- “使用 npm 注册表”
- 变量
- 加密机密
- “工作流中的身份验证”
关于包配置
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 注册表
每次创建新版本时,都可以触发工作流程来发布包。 以下示例中的工作流在 release
事件以 created
类型触发时运行。 如果 CI 测试通过,工作流程将包发布到 npm 注册表。
要根据工作流程中的 npm 注册表执行经过身份验证的操作,您需要将 npm 身份验证令牌作存储为密码。 例如,创建名为 NPM_TOKEN
的存储库机密。 有关详细信息,请参阅“创建和使用已加密的机密。”
默认情况下,npm 使用 package.json 文件的 name
字段来确定已发布包的名称。 当发布到全局命名空间时,您只需要包含包名称。 例如,将名为 npm-hello-world-test
的包发布到 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
环境变量的令牌。
name: Publish Package to npmjs
on:
release:
types: [created]
jobs:
build:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v3
# Setup .npmrc file to publish to npm
- uses: actions/setup-node@v3
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
请注意,需要在 setup-node
中将 registry-url
设置为 https://registry.npmjs.org/
才能正确配置凭据。
发布包到 GitHub Packages
每次创建新版本时,都可以触发工作流程来发布包。 以下示例中的工作流在类型为 created
的 release
事件发生时运行。 如果 CI 测试通过,工作流程会将包发布到 GitHub Packages。
配置目标仓库
使用 repository
键将包链接到 GitHub Packages 是可选操作。 如果未选择在 package.json 文件中提供 repository
键,则 GitHub Packages 会在 package.json 文件的 name
字段中指定的 GitHub 存储库中发布一个包 。 例如,名为 @my-org/test
的包发布到 my-org/test
GitHub 存储库。 如果 repository
键中指定的 url
无效,则包仍可能会发布,但不会按预期链接到存储库源。
但是,如果在 package.json 文件中提供了 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
机密都会设置为存储库的访问令牌。 应在工作流文件中设置此访问令牌的权限,以授予 contents
范围的读取访问权限,并授予 packages
范围的写入访问权限。 有关详细信息,请参阅“使用 GITHUB_TOKEN 进行身份验证。”
如果要将包发布到其他存储库,必须使用对目标存储库中的包具有写入权限的 personal access token (classic)。 有关详细信息,请参阅“创建 personal access token”和“加密机密”。
示例工作流
此示例将 GITHUB_TOKEN
机密存储在 NODE_AUTH_TOKEN
环境变量中。 当 setup-node
操作创建 .npmrc 文件时,它会引用来自 NODE_AUTH_TOKEN
环境变量的令牌。
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@v3
# Setup .npmrc file to publish to GitHub Packages
- uses: actions/setup-node@v3
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 文件。 当对 setup-node
操作使用 scope
输入时,.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 安装和发布包。
name: Publish Package to npmjs
on:
release:
types: [created]
jobs:
build:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v3
# Setup .npmrc file to publish to npm
- uses: actions/setup-node@v3
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 }}