企业官网建设流程全解析

Vitest 贡献指南深度解析：从环境搭建到发布流程的完整开发工作流

【免费下载链接】vitestNext generation testing framework powered by Vite.项目地址: https://gitcode.com/GitHub_Trending/vi/vitest

Vitest 是基于 Vite 的下一代测试框架（仓库根目录 README.md 将其定位为 "Next generation testing framework powered by Vite"）。本文以仓库根目录 CONTRIBUTING.md 为骨架，结合 package.json、pnpm-workspace.yaml、.github下的 CI 工作流与 scripts 目录等真实源码证据，系统讲解如何为 Vitest 贡献代码：从 monorepo 环境搭建、构建与测试，到调试技巧、外部包联调，再到 PR 规范、AI 贡献政策与维护者的发布流程。读完本文，你将掌握在 Vitest 仓库中完整走通"开发—验证—提交—发布"链路的能力。

仓库结构概览：pnpm workspaces 单体仓库

Vitest 仓库是一个典型的 pnpm workspaces 单体仓库（monorepo），这一事实可以从 pnpm-workspace.yaml 的packages字段得到直接印证：

packages: - docs - packages/* - examples/* - test/* - test/e2e/dts/* - test/e2e/fixtures/conditions-pkg

也就是说，仓库被划分为以下几类工作区：

• packages/*：框架本体及其周边包，包括核心的packages/vitest，以及packages/browser、packages/browser-playwright、packages/browser-preview、packages/coverage-istanbul、packages/coverage-v8、packages/expect、packages/mocker、packages/pretty-format、packages/snapshot、packages/spy、packages/ui、packages/utils、packages/web-worker等；
• test/*：各类测试套件（详见下文"测试体系"）；
• examples/*：示例项目；
• docs：文档站点（基于 VitePress）。

正因为是 pnpm workspaces 架构，根 package.json 中明确写有"packageManager": "pnpm@11.24.0"，安装和链接依赖的包管理器必须是 pnpm。仓库还使用了 pnpm 的 catalog、overrides 与 patchedDependencies 机制：例如 pnpm-workspace.yaml 中通过patchedDependencies对@sinonjs/fake-timers@15.4.0、acorn@8.11.3、cac@6.7.14、rrweb-snapshot@2.1.1打补丁（补丁文件位于 patches 目录），并通过overrides统一约束vite、rollup、vitest等关键依赖的版本。

环境搭建与本地开发

推荐工具：ni / nr

贡献指南推荐安装 ni 来在不同包管理器之间无缝切换，ni与nr的等价关系为：

• ni等价于pnpm install；
• nr test等价于pnpm run test。

这可以让你无需记忆每个仓库具体使用哪个包管理器，仓库自带 package.json 中的packageManager字段即可被ni自动识别。

首次构建与开发循环

按照贡献指南，在仓库根目录依次执行：

1. pnpm install：安装全部工作区依赖；
2. pnpm run build：构建所有 monorepo 包。对应根 package.json 中的定义：

"build": "pnpm -r --filter @vitest/ui --filter='./packages/**' run build"

3. 之后可运行pnpm run dev启动监听式重构建，边改代码边自动重建：

"dev": "NODE_OPTIONS=\"--max-old-space-size=8192\" pnpm -r --parallel --filter='./packages/**' run dev"

注意这里通过NODE_OPTIONS把 Node 堆内存上限提升到 8GB，因为并行监听式构建多个包对内存消耗较大。

运行测试

贡献指南给出的测试命令与根 package.json 中的脚本一一对应：

如果使用 VS Code，可以直接按⇧ ⌘ B（macOS）或Ctrl + Shift + B（Windows/Linux）一键启动所有必要的开发任务（build + dev）。

测试体系：按类别组织

测试并非单一目录，而是按类别拆分，这一点在 test/README.md 中有明确说明，仓库 test 目录下也确实存在unit/、e2e/、browser/、coverage-test/、ui/、typescript/、workspaces/、workspaces-browser/等子目录。各分类的定位是：

• core：在单一配置文件下、运行于不同 pool 中的核心测试。这是唯一一个不会为每个测试重新启动 Vitest 实例的类别，适合测试纯函数调用；
• config：测试某个配置选项时放在这里；
• cli：测试复杂交互场景；类型相关的 fixtures 放在test/e2e/dts/；
• browser：测试浏览器模式（Browser Mode）；
• ui：针对 UI 包的 e2e 测试，使用 Playwright 驱动；
• watch：测试文件被创建/更新/删除时 Vitest 的 watch 行为；
• 其余类别则按测试类型分组。

了解这套分类，有助于你新增代码时把测试放到正确的位置，与 CI 的过滤逻辑（--filter '@vitest/test-*' --filter !test-browser）对齐。

UI 开发

如果要改进 Vitest 的浏览器模式（Browser Mode）UI，需要参照 packages/ui/README.md 中关于环境搭建与开发工作流的说明。仓库中 UI 相关的脚本集中在 packages/ui/package.json（如dev:client、build等），根 package.json 也提供了ui:build（vite build packages/ui）、ui:dev、ui:test等快捷命令。

调试技巧：VS Code 断点调试

贡献指南推荐使用 VS Code 自带的 "Run and Debug" 功能来打断点、逐步观察代码执行，完整步骤为：

1. 在你希望暂停执行的位置添加debugger语句；
2. 点击编辑器活动栏中的 "Run and Debug" 图标；
3. 点击 "Javascript Debug Terminal" 按钮；
4. 打开终端后，输入测试命令，例如pnpm run test；
5. 代码执行到debugger处即会暂停，此时可以使用调试工具栏继续执行、单步跳过、重启进程等。

这一流程之所以可行，是因为 VS Code 的 JavaScript 调试终端会把 Node 进程附加到调试器上，Vitest 的测试进程（无论是主进程还是 worker 进程）都会遵守debugger断点。

用本地构建的 Vitest 测试外部包

当你修改了 Vitest 源码，希望用这份"本地版 Vitest"去测试一个正在使用 Vitest 的外部包时，贡献指南给出了基于 pnpmoverrides的完整方案。注意overrides必须写在项目根目录的pnpm-workspace.yaml中：

overrides: vitest: 'link:../path/to/vitest/packages/vitest'

同时需要在外部项目根 package.json 中先把该包声明为依赖：

{ "dependencies": { "vitest": "*" } }

然后在外部项目里重新执行pnpm install完成链接。此外还需要在与package.json同级的目录下放置一个.npmrc文件，写入：

VITEST_MODULE_DIRECTORIES=/node_modules/,/packages/

VITEST_MODULE_DIRECTORIES是 Vitest 用于解析模块目录的环境变量，通过它告知 Vitest 哪些目录会被当作模块查找根，从而让外部包能正确解析到通过link:链接进来的本地 Vitest。

使用未发布的提交（pkg.pr.new）

main分支上的每个提交、以及带有cr-tracked标签的 PR，都会被发布到 pkg.pr.new，因此你可以直接安装某个特定提交构建出的版本：

npm i https://pkg.pr.new/vitest@{commit}

其中{commit}是目标提交的哈希。这对于在外部项目中复现"最新提交是否修复了某个问题"非常实用，无需等待正式发版。仓库 .github/workflows/cr.yml 正是这条发布通道的自动化实现。

Pull Request 规范

基础要求

• 从基础分支（如main）检出主题分支（topic branch），最终合并回该基础分支；
• 新增功能（feature）：
  • 必须附带对应的测试用例；
  • 需要给出有说服力的理由，理想情况下应先在 issue 中提出建议并获得批准后再动手；
  • 当新增 CLI 选项时，运行pnpm -C docs run cli-table来更新cli-generated.md文档。这条命令对应 docs/package.json 中的"cli-table": "tsx .vitepress/scripts/cli-generator.ts"，它会根据 CLI 定义自动生成 docs/guide/cli-generated.md，保证 CLI 文档与实现保持一致；
• 修复缺陷（bug fix）：
  • 如果解决了特定 issue，在 PR 标题中追加(fix #xxxx[,#xxxx])（#xxxx为 issue 编号），便于生成发布日志，例如fix: update entities encoding/decoding (fix #3899)；
  • 在 PR 中提供对 bug 的详细描述，优先附上可运行的演示（live demo）；
  • 在适用的情况下补充测试覆盖；
• 允许 PR 过程中存在多个小提交——GitHub 合并且前会自动 squash；
• 务必保证测试通过；
• 提交信息必须遵循 .github/commit-convention.md 中的约定，这样 changelog 才能自动生成；
• 使用pnpm run lint:fix按项目规范格式化文件（对应根 package.json 中的"lint:fix": "pnpm run lint --fix"）。

提交信息约定

.github/commit-convention.md 明确规定了提交信息的格式。消息必须匹配如下正则：

/^(revert: )?(feat|fix|docs|dx|refactor|perf|test|workflow|build|ci|chore|types|wip|release|deps)(\(.+\))?: .{1,50}/

完整格式为：

<type>(<scope>): <subject> <BLANK LINE> <body> <BLANK LINE> <footer>

要点包括：

• header 必填，scope 可选；
• feat、fix、perf类型会出现在 changelog 中；只要存在BREAKING CHANGE，该提交必然进入 changelog；
• 建议的提交类型：docs、chore、style、refactor、test；
• subject 使用祈使句现在时（"change" 而非 "changed"），首字母不大写，末尾不加句号；
• 正文同样使用祈使句现在时，说明动机并对比原有行为；
• footer 用于标注 Breaking Changes 与关闭的 issue，例如：

perf(build): remove 'foo' option BREAKING CHANGE: The 'foo' option has been removed.

仓库的 PR 模板位于 .github/PULL_REQUEST_TEMPLATE.md，Issue 模板位于 .github/ISSUE_TEMPLATE（包含 bug_report、feature_request、docs 等类型）。

AI 贡献政策

Vitest 团队欢迎把 AI 当作个人助手来使用，但坚持每个 issue 和 PR 背后都必须有一个真实的人。核心要求：

• 所有 issue 和 PR 必须由真人使用官方模板发起；
• 如果 AI 协助创建了 PR，必须披露所使用的工具（如 Claude、Codex、Copilot）；
• 完全由 AI 生成、无真人参与的 PR/issue，会被维护者打上 "maybe automated" 标签，并在 1 天后自动关闭（除非有真人作出非 LLM 撰写的真实回应）；
• 在 issue、PR 或讨论中无价值或含错误信息的 AI 生成评论会被维护者隐藏。

这些措施是为了降低维护负担、保持团队工作效率。这一政策在仓库中并非停留在纸面——.github/workflows/pr-labeled-automated.yml 就是其自动化落地：它使用 agentscan-action 对来源可疑的 PR 账户进行扫描，命中 bot/automation 分类的 PR 会被自动打标并关闭，同时给出申诉渠道；相关辅助逻辑还散落在 .github/actions/send-ai-bot-comment 等 actions 中。

维护指南：发布分支与发布流程

本节主要面向拥有提交权限的维护者，但如果打算做非平凡的代码贡献，通读一遍也很有帮助。

发布分支的命名与映射

公开支持范围记录在 docs/releases.md 中。发布分支的命名规则（注意：这些是分支名，不是 tag 名；tag 永远包含完整版本号，如v4.1.8）：

• main：下一个发布线（release line）的活跃开发分支；
• vN：非 main 主版本N的最新受维护 minor 线；
• vN.M：主版本N下更老的 minor 线，当该精确 minor 仍需要发布或 backport 时保留。

以假设的v5.1.2为最新版本、旧主版本最新发布为v4.1.7与v3.2.4为例，分支形态为：

• main：5.1.x的活跃开发分支；
• v5.0：Vitest 5 下更老的 minor 线；
• v4：Vitest 4 的最新受维护 minor 线，即4.1.x线；
• v4.0：Vitest 4 下更老的 minor 线；
• v3：Vitest 3 的最新受维护 minor 线，即3.2.x线；
• v3.1、v3.0：Vitest 3 下更老的 minor 线；
• v5分支目前还不存在——只有在main进入新的发布线（如6.0.0或6.0.0-beta.x）之后，才会从最新的 v5 minor 创建。

backport 的决策路径为：先在main上按常规落地变更；如果修复目标是主版本N的最新受维护 minor，则目标分支为vN（这是受支持非 main 主版本的默认 backport 目标）；如果还需要更老的受维护 minorN.M，则目标分支为vN.M。backport 的 PR 标题应包含[backport to x]标记，例如fix: [backport to v5.0] ...。分支名永远不包含 patch 版本号。

文档分支

发布分支与文档站点发布线关联：

• main：未发布文档的来源（main 预览站点）；
• release：指向最新稳定发布线（正式文档站点）；发布经理在非 beta 版本发布时手动从main更新它，老线的 backport 不会移动它；
• vN分支：用于旧主版本的文档站点，例如v3对应 v3 的文档站点。

发布流程：PR 驱动 + GitHub Actions

Vitest 的发布（发布 npm 包、创建 git release tag、生成 GitHub Release）不是从维护者本地机器发起的，而是由一个 PR 驱动、由 GitHub Actions 执行。发布 PR 承载版本号 bump，合并该 PR 即触发实际发布。结合 .github/workflows/prepare-publish.yml 与 .github/workflows/publish.yml，完整链路如下：

第 1 步：准备发布 PR。运行Prepare Publish工作流（.github/workflows/prepare-publish.yml），提供两个输入：

• target_branch：与上述发布分支约定匹配的目标分支；Actions 菜单里独立的 "Use workflow from" 选择器应指向同一分支，保证工作流定义与发布目标对齐；
• release或version：版本 bump。默认release: next对稳定版本 bump 到下一个 patch（4.1.2 -> 4.1.3），如果当前已在预发布版本则 bump 到下一个 prerelease（4.2.0-beta.2 -> 4.2.0-beta.3）；否则可指定具体 bump 类型（patch/minor/major/prepatch/preminor/premajor），预发布可传精确version。

该工作流会创建形如prepare-<target_branch>-<release>-<run_id>的分支，运行pnpm run release（即 scripts/release.ts，底层调用bumpp的versionBump，批量 bump 根目录与packages/*下所有包的版本并生成 commit），然后以vitest-release-bot的身份推送分支并打开标题为chore: release v<version>的 PR。想预览release输入会解析成什么版本，可以先在本地交互式运行pnpm release（在确认前取消即可，不会产生任何提交）。

第 2 步：评审并合并 PR。检查版本 bump 后合并，让chore: release v*提交落在发布分支上——正是这个提交触发后续发布。

第 3 步：批准发布工作流。合并会触发Publish Package工作流（.github/workflows/publish.yml）。该工作流首先在Release环境之外运行detect任务，通过git log -1 --format=%s校验 HEAD 提交是否为chore: release v<version>前缀来识别发布提交；确认后才进入environment: Release的publish任务。publish 任务会：检查v<version>tag 是否已存在（防止重复发布）→pnpm install --frozen-lockfile→pnpm build→ 通过pnpm run publish-ci "$VERSION"（即 scripts/publish-ci.ts）以 dry-run 与实际两种方式将包暂存到 npm → 使用 GitHub App 生成的临时 token 推送v<version>tag → 用 changelogithub 生成 changelog。整个流程会在Release环境部署审批处暂停，等待维护者批准。

第 4 步：批准 npm 暂存发布。在 npm 上审查暂存的包，然后用 2FA 批准，发布才真正可安装。之后确认 npm、tag 与 GitHub Release 均正确。

发布保护机制

仓库之外有若干设置守护上述发布流程：GitHub rulesets（防止发布分支和 tag 被手工修改）、Release环境（要求每次发布由维护者审批）、npm 设置（决定包如何发布）。具体包括：

• 保护发布分支：main与v*线设置 branch ruleset——必须有至少一个批准的 PR 且 push 后失效旧审批；仅允许 squash 合并（保证chore: release v*成为干净、可识别的触发提交）；禁止 force-push 与分支删除；必须通过 code scanning。
• 保护 tag：v*发布 tag 设置 tag ruleset——禁止手工创建/更新/删除 tag；只有vitest-release-botGitHub App 可以绕过，v*tag 只能由发布工作流推送。
• Release 环境：Publish Package工作流的部署门禁——必须由维护者批准；禁用自我审批（触发发布的维护者不能批准自己的发布）；部署仅限main与v*分支。
• npm 发布：使用 trusted publishing（OIDC）——每个包的 trusted publisher 将来源仓库、工作流文件与Release环境绑定，发布使用来自该工作流的短期 token，不存在长期 npm token 泄漏风险，并自动携带 provenance 证明，用户可追溯包到具体工作流运行；配合 staged publishing——发布运行只暂存包，维护者在 npm 上用 2FA 审查批准后才正式上线，坏发布可在可安装前被丢弃。

Issue 分诊工作流

贡献指南用一张 Mermaid 流程图完整描述了 Issue 分诊流程，核心决策路径为：未遵循模板 → 关闭并要求按模板重提；重复 issue → 关闭并指向重复项；缺少可复现步骤 → 打needs reproduction标签（bot 会在 3 天无更新后自动关闭）；有复现但非 bug → 判断是否为预期行为，是则解释并关闭，否则保留讨论；确认为 bug → 移除pending triage标签、按需添加功能标签（如feat: browser）、添加优先级标签。优先级分级为：p5紧急（使 Vitest 不可用且影响大多数用户）、p4重要、p3次要缺陷（无 workaround）、p2边缘 case（有 workaround）。仓库中 .github/workflows/issue-labeled.yml、.github/workflows/issue-close-require.yml 等正是这些自动关闭/打标行为的落地。

Pull Request 评审工作流

评审流程同样以流程图明示：区分 bug fix 与 feature 两条路径——

• Feature：讨论必要性 → 确认是否为解决问题的最佳方式 → 评审代码质量 → 添加功能标签 → 强烈确信需要时才批准；
• Bug fix：判断是否为"严格修复"（明显疏漏且无副作用）：是 → 本地验证修复、评审代码质量、按需要求测试用例；否 → 讨论潜在副作用（是否在其他场景引入隐式行为变化、变更是否过大）；
• 两类路径都需添加优先级标签（沿用 issue 分诊工作流）；
• 批准条件：需要 2 名及以上团队成员批准后才合并；使用 "Squash and Merge"；编辑提交信息以符合约定，并在提交信息正文中列出所修复的 issue（如fix #1234, fix #1235）。

依赖管理原则：保持轻量

Vitest 追求轻量，因此在依赖数量与体积上保持克制。贡献指南给出了两条核心原则：

添加依赖前三思

大多数依赖应放在devDependencies，即使运行时也需要。例外情况包括：

• 类型包（如@types/*）；
• 因包含二进制文件而无法正常打包的依赖；
• 自带类型且其类型被 Vitest 自身公开类型使用的依赖。

应避免引入具有庞大传递依赖、相比其功能明显臃肿的依赖。如果某个必需库不符合体积要求，可以尝试 fork 一个精简版本，同时与上游协作把改动合回去。仓库 knip.jsonc 配合根 package.json 中的knip脚本（knip --cache --treat-config-hints-as-errors），正是用来检测未使用依赖与配置、把关依赖卫生的。

添加配置项前三思

Vitest 已经有大量配置选项（见 docs/config 下逐项文档），应避免通过"再加一个选项"来修复问题。添加选项前依次自问：

• 这个问题是否真的值得解决？
• 能否用更聪明的默认值修复？
• 能否用现有选项组合出 workaround？
• 能否用插件（plugin）来解决？

这一原则解释了为什么 Vitest 高度依赖 docs/api/plugin.md 所描述的插件体系来承载定制化需求，而不是无限堆砌配置项。

小结

从本文可以看出，Vitest 的贡献体系是一套高度工程化、自动化与制度化并重的流程：pnpm workspaces 保证多包构建与测试的一致性，build/dev/test脚本让本地开发循环流畅运转，overrides+.npmrc打通了本地构建与外部包联调，pkg.pr.new 让每个提交都可即时安装验证，PR 规范（提交信息约定、CLI 文档自动生成）确保 changelog 与文档长期可维护，而发布分支体系、双工作流（Prepare Publish → Publish）+ 多层发布保护，则让"合并发布 PR → 自动构建发布"的链路既自动化又有人工把关。无论是想提交第一个 bug fix 的贡献者，还是需要 backport 与发版的维护者，都可以从 CONTRIBUTING.md 出发，对照本文梳理的源码与工作流证据按图索骥。

【免费下载链接】vitestNext generation testing framework powered by Vite.项目地址: https://gitcode.com/GitHub_Trending/vi/vitest