Vitest 在 WebStorm 中无法运行，主因是 Node 版本不匹配、Vitest 二进制路径错误或配置文件未被正确加载；需确保 Node ≥20.0.0 且 WebStorm 解释器路径严格一致，vitest.config.ts 置于根目录并手动指定，pnpm monorepo 下需精准定位 vitest.mjs 入口，测试文件须符合命名规范且含顶层 test() 调用。
Vitest 在 WebStorm 里跑不起来，90% 不是配置写错了，而是底层环境或路径没对上——Node 版本、Vitest 二进制位置、配置文件加载这三处卡住，测试图标就根本不出现。
确认 Node ≥20.0.0 且 WebStorm 正在用它
WebStorm 自动识别的 Node 解释器经常“假装”用了 v20+，实际运行时还是系统默认的 v18。终端里 node -v 显示的版本，和 WebStorm Settings → Languages & Frameworks → JavaScript → Node.js 里选中的路径，必须严格一致。
- 别信 “Project” 别名，手动点开文件选择器，精准指向
/path/to/node-v20.12.0/bin/node（macOS/Linux）或C:\Program Files\nodejs\node.exe（Windows） - 如果用 nvm/nvm-windows，确保当前 shell 的
node -v和 WebStorm 里选的一致；nvm 切换后要重启 WebStorm - 运行
vitest报ERR_UNSUPPORTED_ESM_URL_SCHEME？基本就是 Node 版本低于 20 或 WebStorm 没走对解释器
手动指定 vitest.config.ts 并验证是否被加载
WebStorm 不会像命令行那样向上查找 vitest.config.ts。放错位置或命名不标准，等于没配——DOM API 报错、vi.mock 失效、测试文件不出现在边栏，全因配置没生效。
- 配置文件必须放在项目根目录，命名为
vitest.config.ts或vitest.config.js；vitest.conf.mjs、tests/vitest.config.ts都不被自动识别 - 创建运行配置时（Run → Edit Configurations → Vitest），务必填上
Config file字段，指向你的真实路径 - 如果用
vitest.config.ts，确保已安装ts-node，或 WebStorm 的 TypeScript 服务已启用（Settings → Languages & Frameworks → TypeScript）
pnpm monorepo 下精准定位 vitest.mjs 入口
pnpm workspace 中，vitest 很可能不在 node_modules/vitest，而在 node_modules/.pnpm/vitest@4.0.7_... 子目录下。WebStorm 手输路径或依赖自动发现，大概率找不到，直接报 Cannot find module 'vitest'。
- 不要手敲路径：在 Vitest 运行配置页点击右侧文件选择按钮，逐层打开
node_modules，找到真实的vitest.mjs（Vitest 4+ 推荐 ESM 入口，比bin/vitest.js更稳） - 检查
package.json是否仍含"type": "module"和完整"exports"字段；删了会导致 WebStorm 解析不到正确入口 - 如果项目启用了
"type": "module"，但 WebStorm 提示解析失败，先关掉 TypeScript 服务再重开一次，有时缓存会卡住
边栏图标不响应？检查文件名 + 顶层 test 声明
WebStorm 静态扫描测试文件，只认 *.{test,spec}.{js,ts,jsx,tsx} 后缀，并且要求至少一个顶层 test() 或 it() 调用。光有后缀、有 describe，但没顶层 test，图标照样不亮。
- 有效命名：
utils.test.ts、Button.spec.tsx；无效命名：utils.test.ts.cjs、Button.test.tsx.bak - 必须有顶层
test('xxx', () => {})；全包在describe('group', () => { test() })里，且外层没其他test，WebStorm 就认为“这不是可运行测试单元” - 如果用了自定义
include模式（比如加了type-test），仅改vitest.config.ts不够，还得让 WebStorm 读到它——回到上一条，手动指定配置路径
最易忽略的其实是 Node 版本与 WebStorm 解释器的映射关系：哪怕本地装了 v20，WebStorm 若沿用旧项目缓存或系统 PATH 里的 v18，整个 Vitest 启动链就断在第一环，后续所有配置都白搭。调不出来时，先看 node -v 输出，再核对 Settings 里的路径，比反复改 vitest.config.ts 有用得多。
