构建和测试 Node.js

了解如何创建持续集成 (CI) 工作流来构建和测试 Node.js 项目。

本文内容

注意

GitHub Enterprise Server 目前不支持 GitHub 托管的运行器。

简介

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

先决条件

建议基本了解 Node.js、YAML、工作流程配置选项以及如何创建工作流程文件。 有关详细信息，请参阅：

  • 自动标题
  • Node.js 入门

在 GitHub Enterprise Server 上使用自托管的运行器

在包含自承载运行器的 GitHub Enterprise Server 上使用设置操作（例如 actions/setup-LANGUAGE）时，可能需要在无法访问 Internet 的运行器上设置工具缓存。 有关详细信息，请参阅“在未接入互联网的自托管运行器上设置工具缓存”。

使用 Node.js 工作流模板

若要快速开始使用，请将工作流模板添加到存储库的 .github/workflows 目录。

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

  1. 在 GitHub 上，导航到存储库的主页面。1. 在仓库名称下，单击“ Actions”****。

    “github/docs”存储库的选项卡的屏幕截图。 “操作”选项卡以橙色边框突出显示。
    1. 如果存储库中已有工作流，请单击“新建工作流”。

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

  3. 单击“持续集成”以筛选工作流选择。

  4. 在“Node.js”工作流上，单击“配置”。

    如果未找到“Node.js”工作流模板，请将以下工作流代码复制到存储库的 目录中名为 的新文件。

    YAML
    name: Node.js CI

on:
  push:
    branches: [ "main" ]
  pull_request:
    branches: [ "main" ]

jobs:
  build:
    runs-on: ubuntu-latest

    strategy:
      matrix:
        node-version: [18.x, 20.x]
        # See supported Node.js release schedule at https://nodejs.org/en/about/releases/

    steps:
    - uses: actions/checkout@v5
    - name: Use Node.js ${{ matrix.node-version }}
      uses: actions/setup-node@v4
      with:
        node-version: ${{ matrix.node-version }}
        cache: 'npm'
    - run: npm ci
    - run: npm run build --if-present
    - run: npm test

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

  6. 单击“提交更改”。

指定 Node.js 版本

指定 Node.js 版本的最简单方法是使用由 GitHub 提供的 操作。 有关详细信息，请参阅“”。

操作将 Node.js 版本作为输入并在运行器上配置该版本。 此 操作从每个运行器上的工具缓存中查找特定版本的 Node.js，并将必要的二进制文件添加到 ，这可继续用于作业的其余部分。 使用该操作是 Node.js 与 GitHub Actions 结合使用时的推荐方式，因为它能确保不同运行器和不同版本的 Node.js 行为一致。 如果使用自托管运行器，则必须安装 Node.js 并将其添加到 。

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

每个作业都可以使用 上下文访问矩阵 阵列中定义的值。 该 操作使用上下文作为 输入。 操作在构建和测试代码之前使用不同的 Node.js 版本配置每个作业。 有关矩阵策略和上下文的更多信息，请参阅 AUTOTITLE 和 AUTOTITLE。

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

steps:
- uses: actions/checkout@v5
- 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@v5
      - 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 版本。 有关详细信息，请参阅“AUTOTITLE”。

安装依赖

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

可以缓存依赖项来加快工作流运行。 有关详细信息，请参阅“AUTOTITLE”。

使用 npm 的示例

此示例安装 或 文件中的版本，并阻止对锁定文件的更新。 使用通常比运行更快。 有关更多信息，请参阅 和“引入 以实现更快、更可靠的构建”。

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

使用 安装 文件中定义的依赖项。 有关详细信息，请参阅 。

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

使用 Yarn 的示例

此示例安装 文件中定义的依赖项，并阻止对 文件的更新。 有关详细信息，请参阅 。

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

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

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

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

可使用 setup-node 操作在运行器上创建本地 .npmrc 文件以配置默认注册表和范围。 setup-node 操作也接受身份验证令牌作为输入，用于访问私人注册表或发布节点包。 有关详细信息，请参阅 setup-node。

要验证您的私有注册表，需要将 npm 身份验证令牌存储为密码。 例如，创建名为 的存储库机密。 有关详细信息，请参阅“AUTOTITLE”。

在下面的示例中，机密 用于存储 npm 身份验证令牌。 操作配置 文件从 环境变量读取 npm 身份验证令牌。 使用 操作创建 文件时，必须使用包含 npm 身份验证令牌的机密设置 环境变量。

在安装依赖项之前，使用 操作创建 文件。 该操作有两个输入参数。 参数设置 Node.js 版本， 参数设置默认注册表。 如果包注册表使用作用域，你必须使用该参数。 有关详细信息，请参阅 。

YAML
steps:
- uses: actions/checkout@v5
- 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 }}

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

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

缓存依赖项示例

可以使用 操作缓存和还原依赖项。

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

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

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

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

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

YAML
# 此工作流使用未经 GitHub 认证的操作。
# 它们由第三方提供，并受
# 单独的服务条款、隐私政策和支持
# 文档。

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

steps:
- uses: actions/checkout@v5
- 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

如果有自定义要求或需要更精细的缓存控制，可以使用 操作。 有关详细信息，请参阅“AUTOTITLE”。

构建和测试代码

你可以使用与本地相同的命令来构建和测试代码。 例如，如果你运行 <command1> 来执行你文件中定义的构建步骤，并运行 <command2> 来运行你的测试套件，请在工作流文件中添加这些命令。

YAML
steps:
- uses: actions/checkout@v5
- 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

将工作流数据打包为构件

您可以保存构建和测试步骤中的构件以在作业完成后查看。 例如，您可能需要保存日志文件、核心转储、测试结果或屏幕截图。 有关详细信息，请参阅“AUTOTITLE”。

将数据发布到包注册表

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