Vitest配置Skill：让 Vite 项目的测试环境一次配对、一次跑通
- 它是什么：一个专注 Vitest 测试框架配置的知识型 AI 技能（英文名 vitest-configuration，技能ID 13893），覆盖配置文件的编写、Vite 集成、工作区拆分、覆盖率与性能调优。
- 能解决什么：环境选错、别名失效、覆盖率阈值不合理、线程数把机器压垮、模拟状态污染导致测试不稳定等高频“配置坑”。
- 怎么用：安装后无需手动唤醒，当你在 AI 编程助手里提出 Vitest 配置需求时自动生效，直接产出可用的
vitest.config.ts与配套文件。 - 最适合谁：正在用 Vite 做前端或 Node 项目、需要从 Jest 迁移、或要在 monorepo 里统一测试规范的开发者与团队。
- 核心价值：把分散在文档各处的配置项收敛成一份可执行方案，减少反复试错的时间。
1. 该技能叫什么？如何下载安装 AI 技能提升开发效率？
这个技能的中文名是 Vitest配置Skill，英文名为 vitest-configuration，技能 ID 为 13893。
它解决什么问题？ Vitest 由 Vite 驱动，速度快、上手轻，但配置项分散：测试环境要选 node 还是 jsdom、路径别名要与 vite.config 对齐、覆盖率提供者选 V8 还是 Istanbul、线程池开多少才不至于把机器拖死、模拟对象要不要在每次用例后重置……这些问题在官方文档里各占一节，实际开发中往往是“报错了才去翻文档”。该技能把这些配置策略整理成结构化的知识，让 AI 助手在你描述需求时直接给出成套写法，而不是零散片段。
关于安装方式，需要说明两点事实：
- 该技能在定义中标注了
user-invocable: false，即它属于由助手自动加载的知识型技能，不依赖你手动输入斜杠命令唤醒。你只要在对话里表达“帮我配置 Vitest”“从 Jest 迁移到 Vitest”“monorepo 里怎么分工作区跑测试”这类意图，它就会被调用。 - 技能本身的下载与安装入口取决于你使用的 AI 助手平台（技能市场、插件目录或本地技能目录），具体命令与链接以官方说明为准，本文不做假设。
安装前的前提条件（这些是跑通 Vitest 本身必需的）：
- 项目使用 Vite 构建（或至少是 ESM 友好的前端/Node 项目）；
- 已安装 Node.js 与包管理器（npm / yarn / pnpm 任选）；
- 有一个可写入配置文件的工程目录。
验证是否生效：安装完成后，在对话中提问“给一个 TypeScript + React 项目的 vitest.config.ts，要求开启覆盖率阈值 80%”，若助手返回包含 defineConfig、test.environment、coverage.thresholds 等字段的完整配置，并主动提示 setupFiles 与别名配置，说明技能已正常工作。
2. 该技能的主要功能和特点
- 配置文件生成：输出推荐的
vitest.config.ts，涵盖environment、globals、setupFiles、include/exclude、testTimeout、hookTimeout、reporters等常用字段。 - 与 Vite 配置合并：通过
mergeConfig把现有vite.config与 Vitest 专属配置合并，避免别名、插件重复声明。 - 工作区（Workspace）拆分：支持把单元测试、浏览器测试、集成测试拆成多个命名项目，各自指定
include与环境，适合 monorepo。 - 多环境支持：覆盖
node、jsdom、happy-dom、edge-runtime，并演示如何编写自定义环境（含setup与teardown）。 - 设置文件实践：提供
vitest.setup.ts模板，包括扩展匹配器、用例后清理、全局模拟等写法。 - 覆盖率方案：V8 与 Istanbul 两种提供者的差异、报告格式、阈值、
all/clean等选项，以及按文件统计。 - 模块解析排障：路径别名映射、依赖内联（
deps.inline）与外部化（server.deps.external）的取舍。 - 性能调优：
pool选择线程/进程、线程数量上下限、isolate、fileParallelism、maxConcurrency、bail中止策略。 - 类型检查：通过
typecheck配置接入tsc或vue-tsc，并约定类型测试文件命名。 - 避坑清单：直接列出十类常见错误（环境选错、别名缺失、阈值激进、模拟未重置、监听未排除等），比通用文档更贴近排障现场。
和普通工具比强在哪？ 普通做法是“搜索—复制—改错—再搜索”，而这里给出的是一份带取舍理由的方案：为什么用 V8 而不是 Istanbul、为什么 globals: true 要谨慎、线程数为什么不宜盲目调高。它输出的是决策，而不是片段。
3. 如何使用该技能？
第 1 步：安装 Vitest 本体。 技能详情中给出的安装方式如下（三者任选其一）：
npm install -D vitest
# 或
yarn add -D vitest
# 或
pnpm add -D vitest
按需追加附加包：@vitest/ui（可视化界面）、@vitest/browser 与 playwright（浏览器模式）、@vitest/coverage-v8 或 @vitest/coverage-istanbul（覆盖率）。
第 2 步：向助手描述场景。 输入示例：
“这是一个 Vite + React + TypeScript 项目，需要 jsdom 环境，用了
@指向src，希望每次用例后自动清理，覆盖率阈值 80%，CI 里跑一次并输出 JSON 报告。”
第 3 步：接收配置并落盘。 助手会返回 vitest.config.ts，其中包含 test.environment: 'jsdom'、resolve.alias 映射、test.coverage.thresholds 等字段，你复制到项目根目录即可。
第 4 步：接入设置文件。 把公共逻辑（如 @testing-library/react 的 cleanup、全局 fetch 模拟、window.matchMedia 模拟）放进 vitest.setup.ts，并在 test.setupFiles 中引用。
第 5 步：需要多项目时改用工作区。 让助手生成 vitest.workspace.ts，用 defineWorkspace 声明 unit、browser、integration 三组配置，各自 extends 主配置。
第 6 步：补齐脚本。 详情中给出的 package.json 脚本可直接参考：
{
"scripts": {
"test": "vitest",
"test:ui": "vitest --ui",
"test:run": "vitest run",
"test:coverage": "vitest run --coverage",
"test:ci": "vitest run --coverage --reporter=json --reporter=default"
}
}
第 7 步：验证结果。 本地跑 vitest 进入监听模式确认用例通过，再跑 vitest run --coverage 确认覆盖率报告生成、阈值达标。若出现“模块找不到”，优先检查别名是否与 vite.config 一致，这也是该技能常见陷阱清单中的第二条。
4. 同类型竞品对比分析
需要说明：本技能是“配置知识 + 生成能力”，下表的对比对象是测试框架方案本身，用于帮助你判断在什么情况下仍应选择 Vitest，什么情况下该换方案。
| 方案名称 | 定位 | 核心功能 | 安装/使用门槛 | 适用场景 | 优势与不足 |
|---|---|---|---|---|---|
| Vitest（本技能辅助配置） | 由 Vite 驱动的快速单元测试框架 | 复用 Vite 转换与别名、多环境、工作区、V8/Istanbul 覆盖率、浏览器模式、类型检查 | 门槛低，与 Vite 项目天然契合；配置项多，正是本技能的价值所在 | Vite 项目、组件测试、monorepo、需要快速反馈的团队 | 优势：启动快、配置与构建同源、API 兼容 Jest 习惯；不足：脱离 Vite 体系时收益下降，生态插件数量仍少于 Jest |
| Jest | 老牌全功能测试框架 | 快照、模拟、覆盖率、成熟生态 | 中等，需额外配置转换器才能处理 TS/ESM | 历史项目、CRA 体系、依赖大量 Jest 插件的团队 | 优势：生态最全、资料最多；不足：ESM 与 TS 配置繁琐，冷启动较慢 |
| Mocha + Chai | 轻量测试运行器加断言库 | 只提供运行与断言，其余靠插件拼装 | 较高，需自行组合断言、模拟、覆盖率工具 | 需要高度定制、或测试 Node 库的场景 | 优势：灵活、可插拔；不足：开箱能力少，团队规范成本高 |
| Node 内置 test runner | 官方内置测试能力 | 基础运行器、断言、覆盖率（新版） | 极低，无需安装 | 纯 Node 后端、脚本级测试 | 优势：零依赖、稳定；不足：前端组件测试、浏览器环境支持弱 |
选型建议：项目构建基于 Vite、且希望测试与构建共享同一套别名和插件解析，选 Vitest；维护多年的 Webpack 老项目，迁移成本高于收益时，留在 Jest 更稳妥。
5. 该技能的典型应用场景与实际体验情况
场景一：新项目从零搭测试。 前端开发者刚用 Vite 起了一个 React 项目，写第一个用例时卡在“document 未定义”。使用方式是把技术栈和测试类型说清楚，让技能直接给出 jsdom 环境加 cleanup 的设置文件。实际体验是上手几乎无门槛，配置一次到位；注意点是若项目同时含 Node 侧的纯逻辑测试，应按文件后缀或目录拆分，而不是全量套用 jsdom。
场景二：从 Jest 迁移。 团队原有 Jest 配置里有 moduleNameMapper、setupFilesAfterEach 等字段，迁移时最痛的是别名与模拟 API 差异。该技能提供了 mergeConfig 复用 vite.config 的写法，配合 mockReset、restoreMocks、clearMocks 三项开关解决“模拟状态串味”导致的不稳定用例。体验上，迁移后冷启动时间明显缩短；注意点是旧用例里依赖 Jest 私有 API 的部分需要逐个替换，不能一键完成。
场景三：monorepo 多项目并行。 大型代码库中，单元测试、浏览器测试、集成测试的环境要求完全不同。使用 vitest.workspace.ts 拆成命名项目后，可按名字单独运行，CI 也能并行。体验上，配置结构清晰、排查定位快；注意点是工作区里每个项目都要显式 extends 主配置，否则容易漏掉别名定义。
场景四：CI 覆盖率卡口。 团队希望在流水线中设 80% 覆盖率红线。技能给出的 thresholds 支持按行、函数、分支、语句分别设置，并可加 perFile 精细控制。体验上，先在本地跑到阈值再提 PR 能显著减少流水线反复；注意点是阈值不要一步拉满，详情中特别提醒“过于激进的覆盖率阈值会阻碍测试推进”，建议从当前实际值逐步上调。
6. 该技能能为用户带来的价值
- 降低配置门槛：把“环境选型、别名对齐、模拟重置”这些需要经验判断的决策，变成可直接复用的代码模板，新人不必通读文档即可产出可用配置。
- 缩短排障时间：内置的十类常见陷阱清单，覆盖了多数人实际踩过的坑，遇到“找不到模块”“用例互相污染”“监听卡顿”时能快速定位方向。
- 统一团队规范：工作区与脚本约定让多人协作时测试入口、覆盖率口径保持一致，减少“我这里能过、你那里不过”的争论。
- 为长期演进留余地：从单项目配置平滑升级到工作区、从本地监听升级到 CI 全量运行、从 V8 切到 Istanbul，都在同一套结构内完成，避免推倒重建。
- 性能可调：通过线程池、并发度、
bail等参数，让测试速度与机器资源之间取得平衡，大型代码库收益尤其明显。
7. 常见问题 FAQ
Q1：这个技能要怎么安装？需要手动输入命令唤醒吗？
安装入口取决于你使用的 AI 助手平台（技能市场或本地技能目录），具体命令以官方说明为准。该技能定义为不可手动调用（user-invocable: false），属于助手根据对话意图自动加载的知识型技能，你只需正常描述 Vitest 配置需求即可。
Q2：使用这个技能收费吗？
技能本身不包含任何价格信息，是否收费取决于你所在平台的计费规则，请以官方说明为准。技能中涉及的 Vitest 及其附加包（@vitest/ui、@vitest/browser、Playwright、覆盖率提供者）均为开源 npm 依赖，安装命令已在技能中给出。
Q3：我的项目没用 Vite，还能用这个技能吗？
Vitest 本身可以在非 Vite 项目中运行，但该技能的核心价值在于 Vite 集成与配置合并（mergeConfig、别名复用）。如果你的项目基于 Webpack 或 CRA，迁移成本可能高于收益，建议先评估再决定。
Q4：配置里的覆盖率阈值设多少合适？
技能给出的示例是行、函数、分支、语句各 80%，并可开启 perFile 逐文件校验。但详情明确提醒不要设置过于激进的目标，建议先从项目当前真实覆盖率出发，分阶段上调，避免测试因硬性红线被绕过。
Q5：测试跑得慢，应该调哪些参数？
优先检查 pool 选择（线程、进程或 vmThreads）与线程数量上下限，不要盲目调大 maxThreads，线程过多会拖垮系统；同时确认 watchExclude 已排除 node_modules 与构建产物，并评估是否需要用 bail 在首个失败时中止。