我们经常发布文档更新,此页面的翻译可能仍在进行中。有关最新信息,请访问英文文档。如果此页面上的翻译有问题,请告诉我们

构建和测试 Node.js

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

GitHub Actions 可用于 GitHub Free、GitHub Pro、组织的 GitHub Free、GitHub Team、GitHub Enterprise Cloud 和 GitHub One。 GitHub Actions 不适用于使用旧版按仓库计划的帐户所拥有的私有仓库。 For more information, see "GitHub's products."

本文内容

此文档对您有帮助吗?

帮助我们创建出色的文档!

所有 GitHub 文档都是开源的。看到错误或不清楚的内容了吗?提交拉取请求。

做出贡献

或, 了解如何参与。

简介

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

基本要求

建议基本了解 Node.js、YAML、工作流程配置选项以及如何创建工作流程文件。 更多信息请参阅:

从 Node.js 工作流程模板开始

GitHub 提供 Node.js 适用于大多数 Node.js 项目的工作流程模板。 本指南包含可用于自定义模板的 npm 和 Yarn 示例。 更多信息请参阅 Node.js 工作流程模板

要快速开始,请将模板添加到仓库的 .github/workflows 目录中。

YAML
name: Node.js CI

on: [push]

jobs:
  build:

    runs-on: ubuntu-latest

    strategy:
      matrix:
        node-version: [8.x, 10.x, 12.x]

    steps:
    - uses: actions/checkout@v2
    - name: Use Node.js ${{ matrix.node-version }}
      uses: actions/setup-node@v1
      with:
        node-version: ${{ matrix.node-version }}
    - run: npm install
    - run: npm run build --if-present
    - run: npm test
      env:
        CI: true

在其他操作系统上运行

初学者工作流程模板使用 GitHub 托管的 ubuntu-latest 运行器将作业配置为在 Linux 上运行。 您可以更改 runs-on 键,让您的作业在其他操作系统上运行。 例如,您可以使用 GitHub 托管的 Windows 运行器。

runs-on: windows-latest

或者,您可以在 GitHub 托管的 macOS 运行器上运行。

runs-on: macos-latest

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

指定 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 版本 8.x、10.x 和 12.x 构建和测试代码,其中“x”是通配符,匹配可用于版本的最新次要版和补丁版。 "x" 是一个通配符,与版本的最新次要版本和修补程序版本匹配。 node-version 阵列中指定的每个 Node.js 版本都会创建一个运行相同步骤的作业。

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

strategy:
  matrix:
    node-version: [8.x, 10.x, 12.x]

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

您也可以构建和测试精确的 Node.js 版本。

strategy:
  matrix:
    node-version: [8.16.2, 10.17.0]

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

name: Node.js CI

on: [push]

jobs:
  build:

    runs-on: ubuntu-latest

    steps:
    - uses: actions/checkout@v2
    - name: Use Node.js
      uses: actions/setup-node@v1
      with:
        node-version: '12.x'
    - run: npm install
    - run: npm run build --if-present
    - run: npm test
      env:
        CI: true

如果不指定 Node.js 版本,GitHub 将使用环境的默认 Node.js 版本。 更多信息请参阅“GitHub 托管运行器的规范”。

安装依赖项

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

您也可以缓存依赖项来加快工作流程。 更多信息请参阅“缓存依赖项以加快工作流程”。

使用 npm 的示例

此示例安装 package.json 文件中定义的依赖项。 更多信息请参阅 npm install

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

使用 npm ci 将版本安装到 package-lock.jsonnpm-shrinkwraw.json 文件并阻止更新锁定文件。 使用 npm ci 通常比运行 npm install 更快。 更多信息请参阅 npm ci 和“引入 npm ci 以进行更快、更可靠的构建”。

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

使用 Yarn 的示例

此示例安装 package.json 文件中定义的依赖项。 更多信息请参阅 yarn install

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

或者,您可以传递 --frozen-lockfile 来安装 yarn.lock 文件中的版本,并阻止更新 yarn.lock 文件。

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

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

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

要验证您的私有注册表,需要将 npm 身份验证令牌在仓库设置中存储为密码。 例如,创建名为 NPM_TOKEN 的密码。 更多信息请参阅“创建和使用加密密码”。

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

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

steps:
- uses: actions/checkout@v2
- name: Use Node.js
  uses: actions/setup-node@v1
  with:
    always-auth: true
    node-version: '12.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

缓存依赖项示例

您可以使用唯一的密钥缓存依赖项,并在使用 cache 操作运行未来的工作流程时恢复依赖项。 更多信息请参阅“缓存依赖项以加快工作流程”和 cache 操作

steps:
- uses: actions/checkout@v2
- name: Use Node.js
  uses: actions/setup-node@v1
  with:
    node-version: '12.x'
- name: Cache Node.js modules
  uses: actions/cache@v2
  with:
    # npm cache files are stored in `~/.npm` on Linux/macOS
    path: ~/.npm 
    key: ${{ runner.OS }}-node-${{ hashFiles('**/package-lock.json') }}
    restore-keys: |
      ${{ runner.OS }}-node-
      ${{ runner.OS }}-
- name: Install dependencies
  run: npm ci

构建和测试代码

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

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

将工作流数据打包为构件

您可以保存构建和测试步骤中的构件以在作业完成后查看。 例如,您可能需要保存日志文件、核心转储、测试结果或屏幕截图。 更多信息请参阅“使用构件持久化工作流程”。

发布到包注册表

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

此文档对您有帮助吗?

帮助我们创建出色的文档!

所有 GitHub 文档都是开源的。看到错误或不清楚的内容了吗?提交拉取请求。

做出贡献

或, 了解如何参与。