构建和测试 Node.js

您可以创建一个持续集成 (CI) 工作流来构建和测试您的 Node.js 项目。

本文内容

简介

本指南介绍如何创建一个持续集成 (CI) 工作流来构建和测试 Node.js 代码。如果您的 CI 测试通过，您可能需要部署代码或发布包。

先决条件

我们建议您对 Node.js、YAML、工作流配置选项以及如何创建工作流文件有基本的了解。更多信息，请参见

使用 Node.js 工作流模板

要快速入门，请将工作流模板添加到存储库的 .github/workflows 目录。

GitHub 提供了一个 Node.js 工作流模板，该模板应该适用于大多数 Node.js 项目。本指南后续部分将举例说明如何自定义此工作流模板。

  1. 在 GitHub 上，导航到存储库的主页。

  2. 在您的存储库名称下，单击 Actions.

    Screenshot of the tabs for the "github/docs" repository. The "Actions" tab is highlighted with an orange outline.

  3. 如果您的存储库中已存在工作流，请单击 **新建工作流**。

  4. “选择工作流”页面显示推荐的工作流模板列表。搜索“Node.js”。

  5. 点击**持续集成**过滤工作流列表。

  6. 在“Node.js”工作流上，点击**配置**。

  7. 根据需要编辑工作流。例如，更改要使用的 Node 版本。

  8. 点击**提交更改**。

    node.js.yml 工作流文件将添加到仓库的 .github/workflows 目录中。

指定 Node.js 版本

指定 Node.js 版本最简单的方法是使用 GitHub 提供的 setup-node action。更多信息请参见 setup-node。

setup-node action 将 Node.js 版本作为输入，并在运行器上配置该版本。setup-node action 从每个运行器的工具缓存中查找特定版本的 Node.js，并将必要的二进制文件添加到 PATH 中，该路径在作业的剩余时间内保持不变。使用 setup-node action 是在 GitHub Actions 中使用 Node.js 的推荐方法，因为它确保了在不同的运行器和不同的 Node.js 版本之间的一致性。如果您使用的是自托管运行器，则必须安装 Node.js 并将其添加到 PATH 中。

工作流模板包含一个矩阵策略，该策略使用 node-version 中列出的 Node.js 版本构建和测试您的代码。版本号中的“x”是通配符，匹配特定版本可用的最新次要和补丁版本。node-version 数组中指定的每个 Node.js 版本都会创建一个运行相同步骤的作业。

每个作业都可以使用 matrix 上下文访问在矩阵 node-version 数组中定义的值。setup-node action 使用上下文作为 node-version 输入。setup-node action 在构建和测试代码之前为每个作业配置不同的 Node.js 版本。有关矩阵策略和上下文的更多信息，请参见 GitHub Actions 的工作流语法 和 访问有关工作流运行的上下文信息。

YAML
strategy:
  matrix:
    node-version: ['18.x', '20.x']

steps:
- uses: actions/checkout@v4
- name: Use Node.js ${{ matrix.node-version }}
  uses: actions/setup-node@v4
  with:
    node-version: ${{ matrix.node-version }}

或者，您可以使用精确的 Node.js 版本进行构建和测试。

YAML
strategy:
  matrix:
    node-version: ['10.17.0', '17.9.0']

或者，您也可以使用单个版本的 Node.js 进行构建和测试。

YAML
name: Node.js CI

on: [push]

jobs:
  build:

    runs-on: ubuntu-latest

    steps:
      - uses: actions/checkout@v4
      - name: Use Node.js
        uses: actions/setup-node@v4
        with:
          node-version: '20.x'
      - run: npm ci
      - run: npm run build --if-present
      - run: npm test

如果您没有指定 Node.js 版本，GitHub 将使用环境的默认 Node.js 版本。更多信息请参见 使用 GitHub 托管的运行器。

安装依赖项

GitHub 托管的运行器已安装 npm 和 Yarn 依赖项管理器。您可以在构建和测试代码之前使用 npm 和 Yarn 在工作流中安装依赖项。Windows 和 Linux GitHub 托管的运行器也安装了 Grunt、Gulp 和 Bower。

您还可以缓存依赖项以加快工作流速度。更多信息请参见 缓存依赖项以加快工作流速度。

使用 npm 的示例

此示例安装 package-lock.json 或 npm-shrinkwrap.json 文件中的版本，并防止更新锁定文件。使用 npm ci 通常比运行 npm install 更快。更多信息请参见 npm ci 和 为更快、更可靠的构建引入 npm ci。

YAML
steps:
- uses: actions/checkout@v4
- name: Use Node.js
  uses: actions/setup-node@v4
  with:
    node-version: '20.x'
- name: Install dependencies
  run: npm ci

使用 npm install 安装 package.json 文件中定义的依赖项。更多信息请参见 npm install。

YAML
steps:
- uses: actions/checkout@v4
- name: Use Node.js
  uses: actions/setup-node@v4
  with:
    node-version: '20.x'
- name: Install dependencies
  run: npm install

使用 Yarn 的示例

此示例安装 yarn.lock 文件中定义的依赖项，并防止更新 yarn.lock 文件。更多信息请参见 yarn install。

YAML
steps:
- uses: actions/checkout@v4
- name: Use Node.js
  uses: actions/setup-node@v4
  with:
    node-version: '20.x'
- name: Install dependencies
  run: yarn --frozen-lockfile

或者，您可以安装 package.json 文件中定义的依赖项。

YAML
steps:
- uses: actions/checkout@v4
- name: Use Node.js
  uses: actions/setup-node@v4
  with:
    node-version: '20.x'
- name: Install dependencies
  run: yarn

使用私有注册表和创建 .npmrc 文件的示例

您可以使用 setup-node action 在运行器上创建本地 .npmrc 文件，该文件配置默认注册表和作用域。setup-node action 还接受身份验证令牌作为输入，用于访问私有注册表或发布节点包。更多信息请参见 setup-node。

要对您的私有注册表进行身份验证，您需要将您的 npm 身份验证令牌存储为机密。例如，创建一个名为 NPM_TOKEN 的仓库机密。更多信息请参见 在 GitHub Actions 中使用机密。

在下面的示例中，机密 NPM_TOKEN 存储 npm 身份验证令牌。setup-node action 将 .npmrc 文件配置为从 NODE_AUTH_TOKEN 环境变量读取 npm 身份验证令牌。当使用 setup-node action 创建 .npmrc 文件时，您必须使用包含 npm 身份验证令牌的机密设置 NODE_AUTH_TOKEN 环境变量。

在安装依赖项之前，使用 setup-node action 创建 .npmrc 文件。该 action 具有两个输入参数。node-version 参数设置 Node.js 版本，registry-url 参数设置默认注册表。如果您的包注册表使用作用域，则必须使用 scope 参数。更多信息请参见 npm-scope。

YAML
steps:
- uses: actions/checkout@v4
- name: Use Node.js
  uses: actions/setup-node@v4
  with:
    always-auth: true
    node-version: '20.x'
    registry-url: https://registry.npmjs.org
    scope: '@octocat'
- name: Install dependencies
  run: npm ci
  env:
    NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}

上面的示例创建了一个包含以下内容的 .npmrc 文件

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

缓存依赖项示例

您可以使用 setup-node action 缓存和恢复依赖项。

以下示例缓存 npm 的依赖项。

YAML
steps:
- uses: actions/checkout@v4
- uses: actions/setup-node@v4
  with:
    node-version: '20'
    cache: 'npm'
- run: npm install
- run: npm test

以下示例缓存 Yarn 的依赖项。

YAML
steps:
- uses: actions/checkout@v4
- uses: actions/setup-node@v4
  with:
    node-version: '20'
    cache: 'yarn'
- run: yarn
- run: yarn test

以下示例缓存 pnpm (v6.10+) 的依赖项。

YAML
# This workflow uses actions that are not certified by GitHub.
# They are provided by a third-party and are governed by
# separate terms of service, privacy policy, and support
# documentation.

# NOTE: pnpm caching support requires pnpm version >= 6.10.0

steps:
- uses: actions/checkout@v4
- uses: pnpm/action-setup@0609f0983b7a228f052f81ef4c3d6510cae254ad
  with:
    version: 6.10.0
- uses: actions/setup-node@v4
  with:
    node-version: '20'
    cache: 'pnpm'
- run: pnpm install
- run: pnpm test

如果您有自定义需求或需要更精细的缓存控制，您可以使用 cache action。更多信息请参见 缓存依赖项以加快工作流速度。

构建和测试您的代码

您可以使用与您在本地使用的相同的命令来构建和测试您的代码。例如，如果您运行 npm run build 来运行 package.json 文件中定义的构建步骤，并运行 npm test 来运行您的测试套件，则您应该将这些命令添加到您的工作流文件中。

YAML
steps:
- uses: actions/checkout@v4
- name: Use Node.js
  uses: actions/setup-node@v4
  with:
    node-version: '20.x'
- run: npm install
- run: npm run build --if-present
- run: npm test

将工作流数据打包为构件

您可以保存构建和测试步骤中的构件，以便在作业完成后查看。例如，您可能需要保存日志文件、核心转储、测试结果或屏幕截图。更多信息请参见 存储和共享工作流数据。

发布到包注册表

您可以配置您的工作流，以便在 CI 测试通过后将您的 Node.js 包发布到包注册表。有关发布到 npm 和 GitHub Packages 的更多信息，请参见 发布 Node.js 包。