根本原因是vitest.config.ts缺失或导出无效、vitest未本地安装、Testing API未启用；断点不生效主因是未加--no-file-parallelism禁用并行；测试未识别需检查testMatch是否覆盖实际路径。
VSCode里Run Test按钮灰显，根本原因是没启动Vitest测试适配器
灰显不是插件没装，是VSCode压根没识别出任何测试——vitest.config.ts缺失或导出无效是最常见原因。哪怕只写export default {};，也比空文件强。
必须确认三件事：
• 项目根目录存在vitest.config.ts（哪怕最小配置）
• npm install --save-dev vitest已执行（全局安装vitest完全无效）
• 按Ctrl+Shift+P输入Testing: Enable Testing并回车启用Testing API
断点不生效，90%是因为没关掉文件并行执行
Vitest默认用worker并行跑测试，而VSCode调试器只能attach主进程。不加--no-file-parallelism，断点基本等于摆设。
验证方法很简单：
• 打开终端，右上角下拉选JavaScript Debug Terminal
• 运行vitest --no-file-parallelism --test-timeout=0
• 在it()内部打个断点，看是否真能停住
• 如果能，说明逻辑通了；不能，先检查vitest.config.ts里是否漏了@vitejs/plugin-vue或@vitejs/plugin-react（Vue/React项目必配）
Vitest Test Explorer识别不出测试，别怪插件，查testMatch
这个插件不猜路径，只读vitest.config.ts里的testMatch字段。默认只扫**/*.test.{ts,js}和**/*.spec.{ts,js}，你把测试放src/__tests__/就直接被忽略。
显式配置示例：
• testMatch: ['**/__tests__/**/*.test.ts']
• 路径用/或\都行，Vitest内部会normalize
• 改完配置后，VSCode不会自动重载：关掉测试侧边栏，再点左侧试管图标重开；或Ctrl+Shift+P → Vitest: Restart Server
想用UI面板单步跟踪，launch.json里必须设autoAttachChildProcesses: true
VSCode内置“Debug Test”右键菜单经常漏传参数，靠它基本靠不住。稳定做法是手动配launch.json：
{
"version": "0.2.0",
"configurations": [
{
"type": "node",
"request": "launch",
"name": "Debug Vitest",
"autoAttachChildProcesses": true,
"program": "${workspaceRoot}/node_modules/vitest/vitest.mjs",
"args": ["run", "${relativeFile}", "--no-file-parallelism"],
"skipFiles": ["<node_internals>/**", "**/node_modules/**"]
}
]
}</node_internals>
关键点：
• autoAttachChildProcesses: true是跟踪Vitest衍生进程的命脉
• program必须指向node_modules/vitest/vitest.mjs（ESM入口）
• args里必须含--no-file-parallelism，否则单步会跳过断点
• 不要用vitest watch模式配调试，它会持续监听，导致调试器反复attach失败
Vitest调试真正卡点不在UI面板，而在进程模型和source map链路。一旦testMatch配错、--no-file-parallelism漏掉、或Vue/React插件没注册，整个链路就断在第一环——连进it()的机会都没有。
