持续集成

相关源文件

• .github/workflows/auto-start-ci.yml
• .github/workflows/build-tarball.yml
• .github/workflows/commit-lint.yml
• .github/workflows/commit-queue.yml
• .github/workflows/coverage-linux-without-intl.yml
• .github/workflows/coverage-linux.yml
• .github/workflows/coverage-windows.yml
• .github/workflows/daily-wpt-fyi.yml
• .github/workflows/daily.yml
• .github/workflows/doc.yml
• .github/workflows/find-inactive-collaborators.yml
• .github/workflows/find-inactive-tsc.yml
• .github/workflows/linters.yml
• .github/workflows/scorecard.yml
• .github/workflows/test-internet.yml
• .github/workflows/test-linux.yml
• .github/workflows/test-macos.yml
• .github/workflows/tools.yml
• .github/workflows/update-v8.yml

本文档描述了 Node.js 项目中使用的持续集成（CI）系统。它涵盖了确保代码质量和稳定性的 CI 基础设施、工作流和流程。有关内部测试系统本身的信息，请参阅 内部测试系统。有关构建系统的信息，请参阅 构建系统。

Node.js CI 系统概述

Node.js 使用 GitHub Actions 作为其主要的 CI 平台，在多种操作系统和配置上运行一套全面的自动化测试、构建和质量检查。CI 系统在拉取请求和仓库推送时自动触发，确保代码更改在合并前满足项目的质量标准。

CI 系统服务于几个关键目的：

• 验证更改不会破坏现有功能
• 确保跨不同平台的行为一致性
• 衡量和维护代码覆盖率
• 自动化依赖更新
• 强制执行代码风格和文档标准
• 通过提交队列促进自动合并

来源：.github/workflows/test-linux.yml、.github/workflows/test-macos.yml、.github/workflows/coverage-linux.yml、.github/workflows/linters.yml

CI 基础设施

GitHub Actions 架构

Node.js CI 构建于 GitHub Actions 之上，使用一系列工作流文件来定义不同 CI 作业的执行时间和方式。

图示：Node.js CI 架构

来源：.github/workflows/test-linux.yml、.github/workflows/test-macos.yml、.github/workflows/coverage-linux.yml、.github/workflows/coverage-windows.yml、.github/workflows/tools.yml、.github/workflows/commit-queue.yml

并发控制

大多数工作流使用 GitHub Actions 的并发控制，以确保对于给定的分支或拉取请求，一次只运行一个工作流实例。这可以防止资源争用和冲突的测试运行。

并发配置示例

concurrency:
  group: ${{ github.workflow }}-${{ github.head_ref || github.run_id }}
  cancel-in-progress: true

此配置会在推送新提交时取消正在进行的工作流，确保 CI 资源始终在测试最新的代码。

来源：.github/workflows/test-linux.yml、.github/workflows/test-macos.yml、.github/workflows/coverage-linux.yml

核心 CI 工作流

测试工作流

测试工作流是 CI 系统中最关键的部分。它们在不同的操作系统和配置上运行 Node.js 测试套件。

图示：测试工作流架构

来源：.github/workflows/test-linux.yml、.github/workflows/test-macos.yml、.github/workflows/test-internet.yml、.github/workflows/doc.yml

测试工作流的关键方面

1. 平台覆盖：测试在 Linux (x64 和 ARM)、macOS 和 Windows 上运行，以确保跨平台兼容性。

2. 易失性测试检测：测试使用 --measure-flakiness 9 标志来检测和报告易失性测试（有时通过有时失败的测试）。

3. 测试重试策略：FLAKY_TESTS=keep_retrying 环境变量确保在将易失性测试视为失败之前对其进行重试。

4. 特殊测试环境：一些测试在不寻常的环境中运行（例如，带有特殊字符的目录），以捕获边缘情况。

来源：.github/workflows/test-linux.yml、.github/workflows/test-macos.yml

代码覆盖率工作流

代码覆盖率工作流衡量测试套件执行了 Node.js 代码库的多少。它们在 Linux 和 Windows 上运行，并同时衡量 JavaScript 和 C++ 的覆盖率。

工作流	操作系统	特殊配置	覆盖率工具
coverage-linux.yml	Ubuntu 24.04	标准	C8 (JS), gcovr (C++)
coverage-windows.yml	Windows 2022	标准	C8 (仅限 JS)
coverage-linux-without-intl.yml	Ubuntu 24.04	--without-intl	C8 (JS), gcovr (C++)

覆盖率结果会自动上传到 Codecov，Codecov 会跟踪代码覆盖率随时间的变化趋势，并报告拉取请求中的覆盖率变化。

来源：.github/workflows/coverage-linux.yml、.github/workflows/coverage-windows.yml、.github/workflows/coverage-linux-without-intl.yml

构建验证工作流

构建验证工作流确保 Node.js 可以成功构建并打包以供分发。

build-tarball.yml 工作流

1. 使用 make tar 创建源代码 tarball
2. 在干净的环境中提取 tarball
3. 从提取的源代码构建 Node.js
4. 运行测试以验证构建功能正常

此过程模拟了最终用户从源代码下载和构建 Node.js 的体验，确保分发过程正常工作。

来源：.github/workflows/build-tarball.yml

doc.yml 工作流构建和测试 Node.js 文档，确保其格式正确且易于访问。

来源：.github/workflows/doc.yml

质量保证工作流

代码风格检查工作流

代码风格检查系统跨不同文件类型检查代码风格、格式和文档质量。

Linter 类型	目标文件	工具
C++	.cc, .h 文件	ClangFormat, ClangTidy
JavaScript	.js 文件	ESLint
Markdown	.md 文件	Remark
Python	.py 文件	Flake8, Black
YAML	.yml 文件	YAML Linter
Shell	.sh 文件	ShellCheck
Addon 文档	原生插件文档	自定义 Linter
CODEOWNERS	.github/CODEOWNERS	codeowners-validator

来源：.github/workflows/linters.yml

提交消息 linting

commit-lint.yml 工作流验证拉取请求中的第一个提交消息是否符合 Node.js 提交消息指南，该指南遵循一种结构化格式，使项目的历史记录更易于导航和使用。

来源：.github/workflows/commit-lint.yml

供应链安全

scorecard.yml 工作流使用 OpenSSF Scorecard 来评估项目的供应链安全实践，包括依赖管理、构建系统安全和漏洞披露流程。

来源：.github/workflows/scorecard.yml

自动化维护

依赖更新

图示：依赖更新系统

tools.yml 工作流会自动检查 45 个以上依赖项的更新，包括：

• 核心库（libuv, V8, c-ares, nghttp2 等）
• JavaScript 依赖项（acorn, cjs-module-lexer, undici 等）
• 构建工具（gyp-next 等）
• 安全组件（root-certificates）

当有更新可用时，该工作流会创建相应的更改拉取请求，然后由 Node.js 协作者进行审查。

来源：.github/workflows/tools.yml

V8 更新

update-v8.yml 工作流专门处理 V8 JavaScript 引擎的更新，V8 是 Node.js 的关键组成部分。它每周运行一次，检查 V8 的补丁更新，并在有更新可用时创建拉取请求。

来源：.github/workflows/update-v8.yml

项目维护

几个工作流有助于项目维护：

1. 查找不活跃的协作者：find-inactive-collaborators.yml 工作流识别长时间未活跃的协作者，有助于维护准确的活跃贡献者名单。

2. 查找不活跃的 TSC 成员：find-inactive-tsc.yml 工作流识别不活跃的技术指导委员会（TSC）成员，确保治理结构保持最新。

来源：.github/workflows/find-inactive-collaborators.yml、.github/workflows/find-inactive-tsc.yml

自动化工作流

提交队列

提交队列自动化将拉取请求合并到 Node.js 仓库的过程。

图示：提交队列流程

提交队列（commit-queue.yml）每 5 分钟运行一次，检查带有 commit-queue 标签的拉取请求。当它找到符合条件的 PR 时，它会：

1. 验证 CI 是否通过
2. 确保 PR 获得必要的批准
3. 使用 node-core-utils 合并 PR
4. 更新仓库的主分支

带有 fast-track 标签的 PR 在队列中具有优先权。

来源：.github/workflows/commit-queue.yml

自动启动 CI

auto-start-ci.yml 工作流会在带有 request-ci 标签的拉取请求上自动启动 CI。这对于来自 fork 的拉取请求特别有用，因为出于安全限制，CI 可能不会自动运行。

来源：.github/workflows/auto-start-ci.yml

Web 平台测试

daily-wpt-fyi.yml 工作流在不同的 Node.js 版本上运行 Web 平台测试（WPT），并将结果报告给 WPT 仪表板。这有助于确保 Node.js 保持与 Web 标准的兼容性。

来源：.github/workflows/daily-wpt-fyi.yml

与开发工作流程的集成

CI 系统与 Node.js 开发工作流紧密集成。

1. 拉取请求：当打开或更新拉取请求时，CI 系统会自动运行测试、构建和代码风格检查。

2. 提交队列：在拉取请求通过 CI 并获得必要批准后，可以使用提交队列自动合并。

3. 依赖更新：定期自动提出依赖更新，并可在审查后合并。

4. 覆盖率监控：代码覆盖率会随时间跟踪，覆盖率下降会标记出来进行审查。

这种集成确保了 Node.js 代码库保持高质量，同时减少了维护者的手动开销。

来源：.github/workflows/commit-queue.yml、.github/workflows/auto-start-ci.yml

贡献者最佳实践

在处理 Node.js CI 系统时，贡献者应遵循以下最佳实践：

1. 在提交拉取请求之前，**在本地运行测试**，以尽早捕获明显的问题。

2. **及时解决 CI 故障**。CI 故障会阻止合并，需要在 PR 合并前修复。

3. 如果 CI 未在您的 PR 上自动运行，请**添加 request-ci 标签**（对于首次贡献者很常见）。

4. 一旦 PR 准备好合并并通过 CI，请**添加 commit-queue 标签**。

5. 对于需要绕过常规队列的紧急修复，请**添加 fast-track 标签**（需要相应权限）。

遵循这些实践有助于确保与 CI 系统的顺畅交互和贡献的高效处理。

来源：.github/workflows/auto-start-ci.yml、.github/workflows/commit-queue.yml