构建和测试 Node.js

注意：GitHub Enterprise Server 目前不支持 GitHub 托管的运行器。可以在 GitHub public roadmap 上查看有关未来支持计划的更多信息。

简介

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

先决条件

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

“了解 GitHub Actions”
Node.js 入门

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

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

使用 Node.js 入门工作流程

GitHub 提供有 Node.js 入门工作流程，该工作流程将适用于大多数 Node.js 项目。本指南包含可用于自定义入门工作流程的 npm 和 Yarn 示例。有关详细信息，请参阅 Node.js 起始工作流。

在创建构建和测试工作流程时，默认入门工作流程是很好的起点，然后您可以自定义入门工作流程以满足项目的需求。

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

YAML

# 工作流的名称。 GitHub 在存储库的“操作”选项卡下显示工作流的名称。如果省略 `name`，GitHub 会显示相对于存储库根目录的工作流文件路径。
name: Node.js CI

# This example workflow assumes that the default branch for your repository is `main`. If the default branch has a different name, edit this example and add your repository's default branch.
on:
  push:
    branches: [ main ]
  pull_request:
    branches: [ main ]

#
jobs:
  build:

    # <!-- This is a YAML comment for use in annotated code examples. -->
    # 可以使用其他操作系统运行该工作流。
    #
    # 入门工作流使用 GitHub 托管的 `ubuntu-latest` 运行器将作业配置为在 Linux 上运行。 可以更改 `runs-on` 键以在不同的操作系统上运行作业。
    #
    # 例如，你可以通过指定 `runs-on: windows-latest` 使用 GitHub 托管的 Windows 运行器。 或者，你可以使用 `runs-on: macos-latest` 在 GitHub 托管的 macOS 运行器上运行。
    #
    # 您还可以在 Docker 容器中运行作业，或者提供在自己的基础架构上运行的自托管运行器。 有关详细信息，请参阅“[AUTOTITLE](/actions/using-workflows/workflow-syntax-for-github-actions#jobsjob_idruns-on)”。
    runs-on: ubuntu-latest

    # This job uses a matrix strategy to run the job four times, once for each specified Node version. For more information, see "[AUTOTITLE](/actions/using-jobs/using-a-matrix-for-your-jobs)."
    strategy:
      matrix:
        node-version: [14.x, 16.x, 18.x, 20.x]
#
    steps:
      # 该步骤使用 `actions/checkout` 操作在运行器上下载存储库的副本。
      - uses: actions/checkout@v4
      # This step uses the `actions/setup-node` action to set up Node.js for each version indicated by the `matrix.node-version` key above.
      - name: Use Node.js ${{ matrix.node-version }}
        uses: actions/setup-node@v4
        with:
          node-version: ${{ matrix.node-version }}
      # This step runs `npm ci` to install any dependencies listed in your `package.json` file.
      - run: npm ci
      # This step runs the `build` script if there is one specified under the `scripts` key in your `package.json` file.
      - run: npm run build --if-present
      # This step runs the `test` script that is specified under the `scripts` key in your `package.json` file.
      - run: npm test

name: Node.js CI

工作流的名称。 GitHub 在存储库的“操作”选项卡下显示工作流的名称。如果省略 name，GitHub 会显示相对于存储库根目录的工作流文件路径。

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

This example workflow assumes that the default branch for your repository is main. If the default branch has a different name, edit this example and add your repository's default branch.

jobs:
  build:

    runs-on: ubuntu-latest

可以使用其他操作系统运行该工作流。

入门工作流使用 GitHub 托管的 ubuntu-latest 运行器将作业配置为在 Linux 上运行。可以更改 runs-on 键以在不同的操作系统上运行作业。

例如，你可以通过指定 runs-on: windows-latest 使用 GitHub 托管的 Windows 运行器。或者，你可以使用 runs-on: macos-latest 在 GitHub 托管的 macOS 运行器上运行。

您还可以在 Docker 容器中运行作业，或者提供在自己的基础架构上运行的自托管运行器。有关详细信息，请参阅“GitHub Actions 的工作流语法”。

    strategy:
      matrix:
        node-version: [14.x, 16.x, 18.x, 20.x]

This job uses a matrix strategy to run the job four times, once for each specified Node version. For more information, see "对作业使用矩阵."

    steps:

      - uses: actions/checkout@v4

该步骤使用 actions/checkout 操作在运行器上下载存储库的副本。

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

This step uses the actions/setup-node action to set up Node.js for each version indicated by the matrix.node-version key above.

      - run: npm ci

This step runs npm ci to install any dependencies listed in your package.json file.

      - run: npm run build --if-present

This step runs the build script if there is one specified under the scripts key in your package.json file.

      - run: npm test

This step runs the test script that is specified under the scripts key in your package.json file.

# 工作流的名称。 GitHub 在存储库的“操作”选项卡下显示工作流的名称。如果省略 `name`，GitHub 会显示相对于存储库根目录的工作流文件路径。
name: Node.js CI

# This example workflow assumes that the default branch for your repository is `main`. If the default branch has a different name, edit this example and add your repository's default branch.
on:
  push:
    branches: [ main ]
  pull_request:
    branches: [ main ]

#
jobs:
  build:

    # <!-- This is a YAML comment for use in annotated code examples. -->
    # 可以使用其他操作系统运行该工作流。
    #
    # 入门工作流使用 GitHub 托管的 `ubuntu-latest` 运行器将作业配置为在 Linux 上运行。 可以更改 `runs-on` 键以在不同的操作系统上运行作业。
    #
    # 例如，你可以通过指定 `runs-on: windows-latest` 使用 GitHub 托管的 Windows 运行器。 或者，你可以使用 `runs-on: macos-latest` 在 GitHub 托管的 macOS 运行器上运行。
    #
    # 您还可以在 Docker 容器中运行作业，或者提供在自己的基础架构上运行的自托管运行器。 有关详细信息，请参阅“[AUTOTITLE](/actions/using-workflows/workflow-syntax-for-github-actions#jobsjob_idruns-on)”。
    runs-on: ubuntu-latest

    # This job uses a matrix strategy to run the job four times, once for each specified Node version. For more information, see "[AUTOTITLE](/actions/using-jobs/using-a-matrix-for-your-jobs)."
    strategy:
      matrix:
        node-version: [14.x, 16.x, 18.x, 20.x]
#
    steps:
      # 该步骤使用 `actions/checkout` 操作在运行器上下载存储库的副本。
      - uses: actions/checkout@v4
      # This step uses the `actions/setup-node` action to set up Node.js for each version indicated by the `matrix.node-version` key above.
      - name: Use Node.js ${{ matrix.node-version }}
        uses: actions/setup-node@v4
        with:
          node-version: ${{ matrix.node-version }}
      # This step runs `npm ci` to install any dependencies listed in your `package.json` file.
      - run: npm ci
      # This step runs the `build` script if there is one specified under the `scripts` key in your `package.json` file.
      - run: npm run build --if-present
      # This step runs the `test` script that is specified under the `scripts` key in your `package.json` file.
      - run: npm test

指定 Node.js 版本

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

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

入门工作流程包含一个矩阵策略：用四个 Node.js 版本 14.x、16.x、18.x 和 20.x 构建和测试代码。 "x" 是一个通配符，与版本的最新次要版本和修补程序版本匹配。 node-version 数组中指定的每个 Node.js 版本都会创建一个运行相同步骤的作业。

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

YAML

strategy:
  matrix:
    node-version: [14.x, 16.x, 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 }}

strategy:
  matrix:
    node-version: [14.x, 16.x, 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]

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: '18.x'
      - run: npm ci
      - run: npm run build --if-present
      - run: npm test

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: '18.x'
      - run: npm ci
      - run: npm run build --if-present
      - run: npm test

如果不指定 Node.js 版本，GitHub 将使用环境的默认 Node.js 版本。有关详细信息，请参阅“Using GitHub-hosted runners”。

安装依赖关系

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

你还可以缓存依赖项以加快工作流。有关详细信息，请参阅“缓存依赖项以加快工作流程”。

使用 npm 的示例

此示例安装 package-lock.json 或 npm-shrinkwraw.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: '18.x'
- name: Install dependencies
  run: npm ci

steps:
- uses: actions/checkout@v4
- name: Use Node.js
  uses: actions/setup-node@v4
  with:
    node-version: '18.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: '18.x'
- name: Install dependencies
  run: npm install

steps:
- uses: actions/checkout@v4
- name: Use Node.js
  uses: actions/setup-node@v4
  with:
    node-version: '18.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: '18.x'
- name: Install dependencies
  run: yarn --frozen-lockfile

steps:
- uses: actions/checkout@v4
- name: Use Node.js
  uses: actions/setup-node@v4
  with:
    node-version: '18.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: '18.x'
- name: Install dependencies
  run: yarn

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

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

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

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

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

在安装依赖项之前，使用 setup-node 操作创建 .npmrc 文件。该操作有两个输入参数。 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: '18.x'
    registry-url: https://registry.npmjs.org
    scope: '@octocat'
- name: Install dependencies
  run: npm ci
  env:
    NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}

steps:
- uses: actions/checkout@v4
- name: Use Node.js
  uses: actions/setup-node@v4
  with:
    always-auth: true
    node-version: '18.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 操作缓存和还原依赖项。

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

YAML

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

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

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

YAML

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

steps:
- uses: actions/checkout@v4
- uses: actions/setup-node@v4
  with:
    node-version: '14'
    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@v4
- uses: pnpm/action-setup@0609f0983b7a228f052f81ef4c3d6510cae254ad
  with:
    version: 6.10.0
- uses: actions/setup-node@v4
  with:
    node-version: '14'
    cache: 'pnpm'
- run: pnpm install
- run: pnpm test

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

# 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: '14'
    cache: 'pnpm'
- run: pnpm install
- run: pnpm test

如果有自定义要求或需要更精细的缓存控制，可以使用 cache 操作。有关详细信息，请参阅“缓存依赖项以加快工作流程”。

构建和测试代码

您可以使用与本地相同的命令来构建和测试代码。例如，如果你运行 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: '18.x'
- run: npm install
- run: npm run build --if-present
- run: npm test

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

将工作流数据打包为构件

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

发布到包注册表

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

构建和测试 Node.js

本文内容