使用 npm 包与 Actions

使用 GitHub Actions 设置包的发布工作流非常简单。你可以使用 GITHUB_TOKEN 进行身份验证，并利用你所使用的包管理器的原生客户端。如果你想尝试使用 npm，你可以按照这里的逐步说明进行操作： GitHub包示例。

如果你已经在机器上安装了 npm，你可以使用 npm init 创建包。否则，直接复制上述仓库中的 package.json 和 package-lock.json 文件内容。

发布包的工作流很简单。每当创建一个新发布时，工作流就会被触发：

on:
  release:
    types: [created]

这个工作流包含两个任务。第一个任务仅使用 npm 构建和测试包：

build:
  runs-on: ubuntu-latest
  steps:
    - uses: actions/checkout@v2
    - uses: actions/setup-node@v2
      with:
        node-version: 12
    - run: npm ci
    - run: npm test

第二个任务将镜像发布到注册表。此任务需要写入包和读取内容的权限，并使用 ${{ secrets.GITHUB_TOKEN }} 来进行身份验证：

publish-gpr:
  needs: build
  runs-on: ubuntu-latest
  permissions:
    packages: write
    contents: read
  steps:
    - uses: actions/checkout@v2
    - uses: actions/setup-node@v2
      with:
        node-version: 12
        registry-url: https://npm.pkg.github.com/
    - run: npm ci
    - run: npm publish
      env:
        NODE_AUTH_TOKEN: ${{ secrets.GITHUB_TOKEN }}

这个工作流简单地将每次在 GitHub 中创建新发布时，发布一个新的包到 npm 注册表。你可以在 Code | Packages 中找到包的详细信息和设置（见图 8.3）。

image 2024 12 27 13 14 23 513
Figure 1. 图 8.3 – 包的详细信息和设置

然后，你可以在其他项目中使用 npm install @<ownername>/<package-name> 来安装该包。

包的版本不是标签或发布的版本，而是 package.json 文件中的版本。如果你在创建第二次发布时没有更新版本，工作流将会失败。

如果你想自动化此过程，可以使用一些现成的 Actions 来帮助你。你可以使用 NPM-Version 来在发布之前自动设置 npm 的版本。你可以使用发布的名称（github.event.release.name）或标签（github.event.release.tag_name），并将包的版本设置为该值：

- name: 'Change NPM version'
  uses: reedyuk/npm-version@1.1.1
  with:
    version: ${{ github.event.release.tag_name }}

如果你想要一种更灵活的方式，根据标签和分支计算语义版本号，可以使用 [GitVersion](https://gitversion.net/)。GitVersion 是 GitTools actions 的一部分，详情请参阅 [GitTools](https://github.com/marketplace/actions/gittools)。

为了让 GitVersion 正常工作，你需要进行浅克隆。可以通过将 fetch-depth 参数添加到 checkout Action，并设置为 0 来实现：

steps:
  - uses: actions/checkout@v2
    with:
      fetch-depth: 0

接下来，安装 GitVersion 并运行执行操作。如果你想查看语义版本的详细信息，可以设置一个 id：

- name: Install GitVersion
  uses: gittools/actions/gitversion/setup@v0.9.7
  with:
    versionSpec: '5.x'

- name: Determine Version
  id: gitversion
  uses: gittools/actions/gitversion/execute@v0.9.7

计算出的最终语义版本号会存储为环境变量 $GITVERSION_SEMVER。例如，你可以将其作为输入用于 npm-version：

GitVersion 支持配置文件，允许你指定如何计算版本！请参阅 GitVersion 了解更多信息。

如果你需要从 GitVersion 获取详细信息（例如 major、minor 或 patch），你可以将它们作为 gitversion 任务的输出参数访问：

- name: Display GitVersion outputs
  run: |
    echo "Major: ${{ steps.gitversion.outputs.major }}"

使用 GitVersion，你可以扩展工作流以从分支或标签创建包，而不仅仅是发布：

on:
  push:
    tags:
      - 'v*'
    branches:
      - 'release/*'

构建一个具有自动语义版本控制的发布工作流是复杂的，并且在很大程度上取决于你使用的工作流和包管理器。本章的内容应该能帮助你入门。这些技术同样适用于 NuGet、Maven 或任何其他包管理器。