{"meta":{"title":"构建和测试 Node.js","intro":"了解如何创建持续集成 (CI) 工作流来构建和测试 Node.js 项目。","product":"GitHub Actions","breadcrumbs":[{"href":"/zh/enterprise-cloud@latest/actions","title":"GitHub Actions"},{"href":"/zh/enterprise-cloud@latest/actions/tutorials","title":"教程"},{"href":"/zh/enterprise-cloud@latest/actions/tutorials/build-and-test-code","title":"构建和测试代码"},{"href":"/zh/enterprise-cloud@latest/actions/tutorials/build-and-test-code/nodejs","title":"Node.js"}],"documentType":"article"},"body":"# 构建和测试 Node.js\n\n了解如何创建持续集成 (CI) 工作流来构建和测试 Node.js 项目。\n\n## 简介\n\n本指南介绍如何创建用来生成和测试 Node.js 代码的持续集成 (CI) 工作流程。 如果 CI 测试通过，您可能想要部署代码或发布包。\n\n## 先决条件\n\n建议基本了解 Node.js、YAML、工作流程配置选项以及如何创建工作流程文件。 有关详细信息，请参阅：\n\n* ```\n [AUTOTITLE](/actions/learn-github-actions)\n ```\n* ```\n [Node.js 入门](https://nodejs.org/en/docs/guides/getting-started-guide/)\n ```\n\n## 使用 Node.js 工作流模板\n\n若要快速开始使用，请将工作流模板添加到存储库的 `.github/workflows` 目录。\n\nGitHub 为 Node.js 提供了一个工作流模板，适用于大多数 Node.js 项目。 本指南的后续部分提供了如何自定义此工作流模板的示例。\n\n1. 在 GitHub 上，导航到存储库的主页面。1. 在仓库名称下，单击“ Actions”\\*\\*\\*\\*。\n\n ![“github/docs”存储库的选项卡的屏幕截图。 “操作”选项卡以橙色边框突出显示。](/assets/images/help/repository/actions-tab-global-nav-update.png)1. 如果存储库中已有工作流，请单击“新建工作流”。\n\n2. “选择工作流”页面显示一系列推荐的工作流模板。 搜索“Node.js”。\n\n3. 单击“持续集成”\\*\\*\\*\\* 以筛选工作流选择。\n\n4. 在“Node.js”工作流上，单击“**配置**”。\n\n5. 根据需要编辑工作流。 例如更改要使用的 Node 版本。\n\n6. 单击“提交更改”。\n\n工作流文件 `node.js.yml` 将添加到存储库的 `.github/workflows` 目录中。\n\n## 指定 Node.js 版本\n\n指定 Node.js 版本的最简单方法是使用由 GitHub 提供的 `setup-node` 操作。 有关详细信息，请参阅“[`setup-node`](https://github.com/actions/setup-node/)”。\n\n```\n `setup-node` 操作将 Node.js 版本作为输入并在运行器上配置该版本。 此 `setup-node` 操作从每个运行器上的工具缓存中查找特定版本的 Node.js，并将必要的二进制文件添加到 `PATH`，这可继续用于作业的其余部分。 使用 `setup-node` 操作是将 Node.js 与 GitHub Actions 结合使用的推荐方式，因为它能确保在不同的运行环境和 Node.js 的不同版本之间保持一致的行为。 如果使用自托管运行器，则必须安装 Node.js 并将其添加到 `PATH`。\n```\n\n工作流模板包含一个矩阵策略，即使用 `node-version` 中列出的 Node.js 版本构建和测试代码。 版本号中的“x”是一个通配符，与版本的最新次要版本和修补程序版本匹配。\n`node-version` 数组中指定的每个 Node.js 版本都会创建一个运行相同步骤的作业。\n\n每个作业都可以使用 `node-version` 上下文访问矩阵 `matrix` 阵列中定义的值。 该 `setup-node` 操作使用上下文作为 `node-version` 输入。\n`setup-node` 操作在构建和测试代码之前使用不同的 Node.js 版本配置每个作业。 有关矩阵策略和上下文的详细信息，请参阅“[GitHub Actions 的工作流语法](/zh/enterprise-cloud@latest/actions/using-workflows/workflow-syntax-for-github-actions#jobsjob_idstrategymatrix)”和“[上下文参考](/zh/enterprise-cloud@latest/actions/learn-github-actions/contexts)”。\n\n```yaml copy\nstrategy:\n matrix:\n node-version: ['18.x', '20.x']\n\nsteps:\n- uses: actions/checkout@v5\n- name: Use Node.js ${{ matrix.node-version }}\n uses: actions/setup-node@v4\n with:\n node-version: ${{ matrix.node-version }}\n```\n\n您也可以构建和测试精确的 Node.js 版本。\n\n```yaml copy\nstrategy:\n matrix:\n node-version: ['10.17.0', '17.9.0']\n```\n\n或者，您也可以使用单个版本的 Node.js 构建和测试。\n\n```yaml copy\nname: Node.js CI\n\non: [push]\n\njobs:\n build:\n\n runs-on: ubuntu-latest\n\n steps:\n - uses: actions/checkout@v5\n - name: Use Node.js\n uses: actions/setup-node@v4\n with:\n node-version: '20.x'\n - run: npm ci\n - run: npm run build --if-present\n - run: npm test\n```\n\n如果不指定 Node.js 版本，GitHub 将使用环境的默认 Node.js 版本。\n有关详细信息，请参阅“[GitHub 托管的运行程序](/zh/enterprise-cloud@latest/actions/using-github-hosted-runners/about-github-hosted-runners#supported-software)”。\n\n## 安装依赖\n\nGitHub 托管运行器安装了 npm 和 Yarn 依赖管理工具。 在构建和测试代码之前，可以使用 npm 和 Yarn 在工作流程中安装依赖项。 Windows 和 Linux GitHub 托管的运行器也安装了 Grunt、Gulp 和 Bower。\n\n可以缓存依赖项来加快工作流运行。 有关详细信息，请参阅“[依赖项缓存参考](/zh/enterprise-cloud@latest/actions/using-workflows/caching-dependencies-to-speed-up-workflows)”。\n\n### 使用 npm 的示例\n\n此示例安装 `package-lock.json` 或 `npm-shrinkwrap.json` 文件中的版本，并阻止对锁定文件的更新。 使用 `npm ci` 通常比运行 `npm install` 更快。 有关详细信息，请参阅 [`npm ci`](https://docs.npmjs.com/cli/ci.html) 和“[引入 `npm ci` 以实现更快、更可靠的生成](https://blog.npmjs.org/post/171556855892/introducing-npm-ci-for-faster-more-reliable)”。\n\n```yaml copy\nsteps:\n- uses: actions/checkout@v5\n- name: Use Node.js\n uses: actions/setup-node@v4\n with:\n node-version: '20.x'\n- name: Install dependencies\n run: npm ci\n```\n\n使用 `npm install` 会安装 `package.json` 文件中定义的依赖项。 有关详细信息，请参阅 [`npm install`](https://docs.npmjs.com/cli/install)。\n\n```yaml copy\nsteps:\n- uses: actions/checkout@v5\n- name: Use Node.js\n uses: actions/setup-node@v4\n with:\n node-version: '20.x'\n- name: Install dependencies\n run: npm install\n```\n\n### 使用 Yarn 的示例\n\n此示例安装 `yarn.lock` 文件中定义的依赖项，并阻止对 `yarn.lock` 文件的更新。 有关详细信息，请参阅 [`yarn install`](https://yarnpkg.com/en/docs/cli/install)。\n\n```yaml copy\nsteps:\n- uses: actions/checkout@v5\n- name: Use Node.js\n uses: actions/setup-node@v4\n with:\n node-version: '20.x'\n- name: Install dependencies\n run: yarn --frozen-lockfile\n```\n\n或者，可以安装 `package.json` 文件中定义的依赖项。\n\n```yaml copy\nsteps:\n- uses: actions/checkout@v5\n- name: Use Node.js\n uses: actions/setup-node@v4\n with:\n node-version: '20.x'\n- name: Install dependencies\n run: yarn\n```\n\n### 使用私有注册表并创建 .npmrc 文件的示例\n\n可使用 `setup-node` 操作在运行器上创建本地 `.npmrc` 文件以配置默认注册表和范围。 `setup-node` 操作也接受身份验证令牌作为输入，用于访问私人注册表或发布节点包。 有关详细信息，请参阅 [`setup-node`](https://github.com/actions/setup-node/)。\n\n要验证您的私有注册表，需要将 npm 身份验证令牌存储为密码。 例如，创建名为 `NPM_TOKEN` 的存储库机密。 有关详细信息，请参阅“[在 GitHub Actions 中使用机密](/zh/enterprise-cloud@latest/actions/security-guides/using-secrets-in-github-actions)”。\n\n在下面的示例中，机密 `NPM_TOKEN` 用于存储 npm 身份验证令牌。\n`setup-node` 操作配置 `.npmrc` 文件从 `NODE_AUTH_TOKEN` 环境变量读取 npm 身份验证令牌。 使用 `setup-node` 操作创建 `.npmrc` 文件时，必须使用包含 npm 身份验证令牌的机密设置 `NODE_AUTH_TOKEN` 环境变量。\n\n在安装依赖项之前，使用 `setup-node` 操作创建 `.npmrc` 文件。 该操作有两个输入参数。\n`node-version` 参数设置 Node.js 版本，`registry-url` 参数设置默认注册表。 如果包注册表使用作用域，你必须使用 `scope` 参数。 有关详细信息，请参阅 [`npm-scope`](https://docs.npmjs.com/misc/scope)。\n\n```yaml copy\nsteps:\n- uses: actions/checkout@v5\n- name: Use Node.js\n uses: actions/setup-node@v4\n with:\n always-auth: true\n node-version: '20.x'\n registry-url: https://registry.npmjs.org\n scope: '@octocat'\n- name: Install dependencies\n run: npm ci\n env:\n NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}\n```\n\n上面的示例创建了一个包含以下内容的 `.npmrc` 文件：\n\n```shell\n//registry.npmjs.org/:_authToken=${NODE_AUTH_TOKEN}\n@octocat:registry=https://registry.npmjs.org/\nalways-auth=true\n```\n\n### 缓存依赖项示例\n\n可以使用 [`setup-node` 操作](https://github.com/actions/setup-node)缓存和还原依赖项。\n\n以下示例缓存 npm 的依赖项。\n\n```yaml copy\nsteps:\n- uses: actions/checkout@v5\n- uses: actions/setup-node@v4\n with:\n node-version: '20'\n cache: 'npm'\n- run: npm install\n- run: npm test\n```\n\n以下示例缓存 Yarn 的依赖项。\n\n```yaml copy\nsteps:\n- uses: actions/checkout@v5\n- uses: actions/setup-node@v4\n with:\n node-version: '20'\n cache: 'yarn'\n- run: yarn\n- run: yarn test\n```\n\n以下示例缓存 pnpm (v6.10+) 的依赖项。\n\n```yaml copy\n# 此工作流使用未经 GitHub 认证的操作。\n# 它们由第三方提供，并受\n# 单独的服务条款、隐私政策和支持\n# 文档。\n\n# NOTE: pnpm caching support requires pnpm version >= 6.10.0\n\nsteps:\n- uses: actions/checkout@v5\n- uses: pnpm/action-setup@0609f0983b7a228f052f81ef4c3d6510cae254ad\n with:\n version: 6.10.0\n- uses: actions/setup-node@v4\n with:\n node-version: '20'\n cache: 'pnpm'\n- run: pnpm install\n- run: pnpm test\n```\n\n如果有自定义要求或需要更精细的缓存控制，可以使用 [`cache` 操作](https://github.com/marketplace/actions/cache)。 有关详细信息，请参阅“[依赖项缓存参考](/zh/enterprise-cloud@latest/actions/using-workflows/caching-dependencies-to-speed-up-workflows)”。\n\n## 构建和测试代码\n\n你可以使用与本地相同的命令来构建和测试代码。 例如，如果你运行 `npm run build` 来运行 `package.json` 文件中定义的构建步骤，且运行 `npm test` 来运行测试套件，请在工作流文件中添加以下命令。\n\n```yaml copy\nsteps:\n- uses: actions/checkout@v5\n- name: Use Node.js\n uses: actions/setup-node@v4\n with:\n node-version: '20.x'\n- run: npm install\n- run: npm run build --if-present\n- run: npm test\n```\n\n## 将工作流数据打包为构件\n\n您可以保存构建和测试步骤中的构件以在作业完成后查看。 例如，您可能需要保存日志文件、核心转储、测试结果或屏幕截图。 有关详细信息，请参阅“[使用工作流工件存储和共享数据](/zh/enterprise-cloud@latest/actions/using-workflows/storing-workflow-data-as-artifacts)”。\n\n## 将数据发布到包注册表\n\n您可以配置工作流程在 CI 测试通过后将 Node.js 包发布到包注册表。 有关发布到 npm 和 GitHub Packages 的详细信息，请参阅“[发布 Node.js 包](/zh/enterprise-cloud@latest/actions/publishing-packages/publishing-nodejs-packages)”。"}