Vitest 贡献指南深度解析从环境搭建到发布流程的完整开发工作流【免费下载链接】vitestNext generation testing framework powered by Vite.项目地址: https://gitcode.com/GitHub_Trending/vi/vitestVitest 是基于 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: pnpm11.24.0安装和链接依赖的包管理器必须是 pnpm。仓库还使用了 pnpm 的 catalog、overrides 与 patchedDependencies 机制例如 pnpm-workspace.yaml 中通过patchedDependencies对sinonjs/fake-timers15.4.0、acorn8.11.3、cac6.7.14、rrweb-snapshot2.1.1打补丁补丁文件位于 patches 目录并通过overrides统一约束vite、rollup、vitest等关键依赖的版本。环境搭建与本地开发推荐工具ni / nr贡献指南推荐安装 ni 来在不同包管理器之间无缝切换ni与nr的等价关系为ni等价于pnpm installnr test等价于pnpm run test。这可以让你无需记忆每个仓库具体使用哪个包管理器仓库自带 package.json 中的packageManager字段即可被ni自动识别。首次构建与开发循环按照贡献指南在仓库根目录依次执行pnpm install安装全部工作区依赖pnpm run build构建所有 monorepo 包。对应根 package.json 中的定义build: pnpm -r --filter vitest/ui --filter./packages/** run build之后可运行pnpm run dev启动监听式重构建边改代码边自动重建dev: NODE_OPTIONS\--max-old-space-size8192\ pnpm -r --parallel --filter./packages/** run dev注意这里通过NODE_OPTIONS把 Node 堆内存上限提升到 8GB因为并行监听式构建多个包对内存消耗较大。运行测试贡献指南给出的测试命令与根 package.json 中的脚本一一对应命令作用对应脚本定义pnpm run test运行核心测试pnpm --filter test-unit test:threadspnpm run test:ci运行全量测试套件CI 模式CItrue pnpm -r ... --filter vitest/test-* --filter !test-browser run testcd test/(dir) pnpm run test运行某个具体测试套件各测试工作区自带脚本如果使用 VS Code可以直接按⇧ ⌘ BmacOS或Ctrl Shift BWindows/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 Modeui针对 UI 包的 e2e 测试使用 Playwright 驱动watch测试文件被创建/更新/删除时 Vitest 的 watch 行为其余类别则按测试类型分组。了解这套分类有助于你新增代码时把测试放到正确的位置与 CI 的过滤逻辑--filter vitest/test-* --filter !test-browser对齐。UI 开发如果要改进 Vitest 的浏览器模式Browser ModeUI需要参照 packages/ui/README.md 中关于环境搭建与开发工作流的说明。仓库中 UI 相关的脚本集中在 packages/ui/package.json如dev:client、build等根 package.json 也提供了ui:buildvite build packages/ui、ui:dev、ui:test等快捷命令。调试技巧VS Code 断点调试贡献指南推荐使用 VS Code 自带的 Run and Debug 功能来打断点、逐步观察代码执行完整步骤为在你希望暂停执行的位置添加debugger语句点击编辑器活动栏中的 Run and Debug 图标点击 Javascript Debug Terminal 按钮打开终端后输入测试命令例如pnpm run test代码执行到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.newmain分支上的每个提交、以及带有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、testsubject 使用祈使句现在时change 而非 changed首字母不大写末尾不加句号正文同样使用祈使句现在时说明动机并对比原有行为footer 用于标注 Breaking Changes 与关闭的 issue例如perf(build): remove foo option BREAKING CHANGE: The foo option has been removed.仓库的 PR 模板位于 .github/PULL_REQUEST_TEMPLATE.mdIssue 模板位于 .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.8main下一个发布线release line的活跃开发分支vN非 main 主版本N的最新受维护 minor 线vN.M主版本N下更老的 minor 线当该精确 minor 仍需要发布或 backport 时保留。以假设的v5.1.2为最新版本、旧主版本最新发布为v4.1.7与v3.2.4为例分支形态为main5.1.x的活跃开发分支v5.0Vitest 5 下更老的 minor 线v4Vitest 4 的最新受维护 minor 线即4.1.x线v4.0Vitest 4 下更老的 minor 线v3Vitest 3 的最新受维护 minor 线即3.2.x线v3.1、v3.0Vitest 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 ActionsVitest 的发布发布 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 到下一个 patch4.1.2 - 4.1.3如果当前已在预发布版本则 bump 到下一个 prerelease4.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 vversion的 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 vversion前缀来识别发布提交确认后才进入environment: Release的publish任务。publish 任务会检查vversiontag 是否已存在防止重复发布→pnpm install --frozen-lockfile→pnpm build→ 通过pnpm run publish-ci $VERSION即 scripts/publish-ci.ts以 dry-run 与实际两种方式将包暂存到 npm → 使用 GitHub App 生成的临时 token 推送vversiontag → 用 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。保护 tagv*发布 tag 设置 tag ruleset——禁止手工创建/更新/删除 tag只有vitest-release-botGitHub App 可以绕过v*tag 只能由发布工作流推送。Release 环境Publish Package工作流的部署门禁——必须由维护者批准禁用自我审批触发发布的维护者不能批准自己的发布部署仅限main与v*分支。npm 发布使用 trusted publishingOIDC——每个包的 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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 Vitest 贡献指南深度解析：从环境搭建到发布流程的完整开发工作流
Vitest 贡献指南深度解析从环境搭建到发布流程的完整开发工作流【免费下载链接】vitestNext generation testing framework powered by Vite.项目地址: https://gitcode.com/GitHub_Trending/vi/vitestVitest 是基于 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: pnpm11.24.0安装和链接依赖的包管理器必须是 pnpm。仓库还使用了 pnpm 的 catalog、overrides 与 patchedDependencies 机制例如 pnpm-workspace.yaml 中通过patchedDependencies对sinonjs/fake-timers15.4.0、acorn8.11.3、cac6.7.14、rrweb-snapshot2.1.1打补丁补丁文件位于 patches 目录并通过overrides统一约束vite、rollup、vitest等关键依赖的版本。环境搭建与本地开发推荐工具ni / nr贡献指南推荐安装 ni 来在不同包管理器之间无缝切换ni与nr的等价关系为ni等价于pnpm installnr test等价于pnpm run test。这可以让你无需记忆每个仓库具体使用哪个包管理器仓库自带 package.json 中的packageManager字段即可被ni自动识别。首次构建与开发循环按照贡献指南在仓库根目录依次执行pnpm install安装全部工作区依赖pnpm run build构建所有 monorepo 包。对应根 package.json 中的定义build: pnpm -r --filter vitest/ui --filter./packages/** run build之后可运行pnpm run dev启动监听式重构建边改代码边自动重建dev: NODE_OPTIONS\--max-old-space-size8192\ pnpm -r --parallel --filter./packages/** run dev注意这里通过NODE_OPTIONS把 Node 堆内存上限提升到 8GB因为并行监听式构建多个包对内存消耗较大。运行测试贡献指南给出的测试命令与根 package.json 中的脚本一一对应命令作用对应脚本定义pnpm run test运行核心测试pnpm --filter test-unit test:threadspnpm run test:ci运行全量测试套件CI 模式CItrue pnpm -r ... --filter vitest/test-* --filter !test-browser run testcd test/(dir) pnpm run test运行某个具体测试套件各测试工作区自带脚本如果使用 VS Code可以直接按⇧ ⌘ BmacOS或Ctrl Shift BWindows/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 Modeui针对 UI 包的 e2e 测试使用 Playwright 驱动watch测试文件被创建/更新/删除时 Vitest 的 watch 行为其余类别则按测试类型分组。了解这套分类有助于你新增代码时把测试放到正确的位置与 CI 的过滤逻辑--filter vitest/test-* --filter !test-browser对齐。UI 开发如果要改进 Vitest 的浏览器模式Browser ModeUI需要参照 packages/ui/README.md 中关于环境搭建与开发工作流的说明。仓库中 UI 相关的脚本集中在 packages/ui/package.json如dev:client、build等根 package.json 也提供了ui:buildvite build packages/ui、ui:dev、ui:test等快捷命令。调试技巧VS Code 断点调试贡献指南推荐使用 VS Code 自带的 Run and Debug 功能来打断点、逐步观察代码执行完整步骤为在你希望暂停执行的位置添加debugger语句点击编辑器活动栏中的 Run and Debug 图标点击 Javascript Debug Terminal 按钮打开终端后输入测试命令例如pnpm run test代码执行到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.newmain分支上的每个提交、以及带有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、testsubject 使用祈使句现在时change 而非 changed首字母不大写末尾不加句号正文同样使用祈使句现在时说明动机并对比原有行为footer 用于标注 Breaking Changes 与关闭的 issue例如perf(build): remove foo option BREAKING CHANGE: The foo option has been removed.仓库的 PR 模板位于 .github/PULL_REQUEST_TEMPLATE.mdIssue 模板位于 .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.8main下一个发布线release line的活跃开发分支vN非 main 主版本N的最新受维护 minor 线vN.M主版本N下更老的 minor 线当该精确 minor 仍需要发布或 backport 时保留。以假设的v5.1.2为最新版本、旧主版本最新发布为v4.1.7与v3.2.4为例分支形态为main5.1.x的活跃开发分支v5.0Vitest 5 下更老的 minor 线v4Vitest 4 的最新受维护 minor 线即4.1.x线v4.0Vitest 4 下更老的 minor 线v3Vitest 3 的最新受维护 minor 线即3.2.x线v3.1、v3.0Vitest 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 ActionsVitest 的发布发布 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 到下一个 patch4.1.2 - 4.1.3如果当前已在预发布版本则 bump 到下一个 prerelease4.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 vversion的 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 vversion前缀来识别发布提交确认后才进入environment: Release的publish任务。publish 任务会检查vversiontag 是否已存在防止重复发布→pnpm install --frozen-lockfile→pnpm build→ 通过pnpm run publish-ci $VERSION即 scripts/publish-ci.ts以 dry-run 与实际两种方式将包暂存到 npm → 使用 GitHub App 生成的临时 token 推送vversiontag → 用 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。保护 tagv*发布 tag 设置 tag ruleset——禁止手工创建/更新/删除 tag只有vitest-release-botGitHub App 可以绕过v*tag 只能由发布工作流推送。Release 环境Publish Package工作流的部署门禁——必须由维护者批准禁用自我审批触发发布的维护者不能批准自己的发布部署仅限main与v*分支。npm 发布使用 trusted publishingOIDC——每个包的 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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考