WebStorm 调试 Jest 需满足三个前提：正确配置 Node.js 解释器、项目根目录存在 jest.config.js 或 package.json 含 test 脚本、Jest package 字段指向本地可执行入口；任一缺失将导致断点失效、调试按钮灰显或报错。
WebStorm 能直接调试 Jest 测试，但必须满足三个前提：Node.js 解释器已识别、Jest 环境被正确“认出”、运行配置指向真实可执行入口——缺一不可，否则断点不生效、调试按钮灰掉或直接报错。
为什么断点不暂停？先确认 Node.js 解释器是否真被识别
WebStorm 不会自动继承系统 PATH 或 nvm 切换后的 node 版本，调试失败的第一排查点永远是解释器路径是否真实有效：
- 进入
File → Settings → Languages & Frameworks → Node.js and NPM，检查Node interpreter字段是否显示绿色对勾；若为红标或Not configured，手动点击右侧文件夹图标选择本地node可执行文件（如/usr/local/bin/node或C:\Program Files\nodejs\node.exe） - 如果用
nvm或fnm，确保当前终端里which node输出的路径与 WebStorm 中填写的一致；切换版本后必须重启 WebStorm，否则缓存仍指向旧版本 - 解释器未识别会导致“Run”按钮灰掉、“Debug”不可点击，且所有 Jest 配置项（如
Jest package）下拉列表为空
右键没 “Debug Jest”？补全 Jest 的“存在凭证”
WebStorm 不扫描 node_modules，它只靠两个硬性信号判断 Jest 是否可用：
- 项目根目录（即含
package.json的那层）存在jest.config.js或jest.config.ts - 或
package.json的scripts中定义了"test": "jest"（值可以带参数，如"jest --runInBand"） - 两者都缺时，右键测试文件不会出现任何 Jest 相关菜单项；此时即使装了
jest也无效
调试启动失败：Jest package 路径必须指向本地入口
报错 Cannot find module 'jest-cli' 或 Command failed: node .../jest.js，90% 是因为 Jest package 字段填了全局路径：
- 打开
Run → Edit Configurations → + → Jest，在Jest package字段中：
– npm/yarn 项目填相对路径：node_modules/.bin/jest
– pnpm 项目填：node_modules/jest/bin/jest.js（.bin/jest是坏链接）
– 绝对路径（如/usr/local/bin/jest）一律禁用 - 强烈建议勾选
Automatic模式，让 WebStorm 自动解析本地node_modules，但改完必须重启 IDE 才生效 -
Working directory必须设为项目根目录（即package.json所在层），否则moduleNameMapper、setupFilesAfterEnv中的相对路径全部失效，导致Cannot find module 'xxx'
断点进了 but 卡住 or 报 Timeout？异步逻辑和 Jest 启动模式要对齐
WebStorm 的 Debug 是全新进程，不继承 CLI 下 jest --watch 的 mock 状态或缓存，单步调试时容易因超时或 Promise 未 resolve 而卡死：
- 异步测试（
it('xxx', async () => { ... })）必须return一个 Promise 或显式await，不能混用done()；否则 Jest 等不到回调，触发默认 5 秒超时 - 调试单个
it时，Jest 默认仍会扫描全项目匹配testMatch，造成启动慢；可在Jest Options字段加--testNamePattern="your test name"缩小范围 - 临时延长超时：在测试文件顶部加
jest.setTimeout(10000)；长期方案是在jest.config.js中设testTimeout: 10000 - 若调试时变量值显示
undefined或调用栈异常，检查ts-jest是否启用 source map（ts-jest配置中需有sourceMap: true）
真正卡住的地方往往不是断点本身，而是 Jest 启动那一刻——工作目录错、解释器错、Jest 入口错，三者任一出问题，调试器连进程都起不来。别急着加断点，先让 Run 按钮能点下去、控制台能打出 ✓。
