VSCode调试Mocha失败主因是环境配置不当：需确认Node.js≥14、Mocha本地安装时用npx或指向node_modules/_mocha路径、TypeScript项目启用sourceMap并添加ts-node/register。
VSCode 调试 Mocha 时 launch.json 配置不生效？先确认 Node.js 版本和 Mocha 安装方式
VSCode 调试 Mocha 失败，八成卡在环境前提上。Mocha 本身不提供调试入口，得靠 VSCode 的 Node.js 调试器启动它，所以 node 和 mocha 必须能被终端直接调用。
- 运行
node -v确认 Node.js ≥ 14（推荐 16+），低于 12 的版本不支持--inspect参数 - 检查
mocha是全局安装（npm install -g mocha）还是项目本地安装（npm install mocha --save-dev）：本地安装时，VSCode 必须用npx mocha启动，否则找不到命令 - 如果用 TypeScript 写测试，
mocha不会自动编译.ts文件，必须加--require ts-node/register或用ts-mocha
最简可用的 launch.json 配置（Node.js + Mocha + 本地依赖）
不用花哨参数，先跑通再优化。以下配置适用于绝大多数 npm script 式项目（mocha 在 devDependencies 中）：
{
"version": "0.2.0",
"configurations": [
{
"type": "node",
"request": "launch",
"name": "Mocha Current File",
"program": "${workspaceFolder}/node_modules/mocha/bin/_mocha",
"args": [
"${file}",
"--timeout",
"5000",
"--colors"
],
"console": "integratedTerminal",
"internalConsoleOptions": "neverOpen",
"skipFiles": ["<node_internals>/**"]
}
]
}
-
program指向本地_mocha入口（不是mocha命令），避免 shell 解析问题 -
${file}表示当前打开的测试文件，调试单个文件时最方便；想跑整个test/目录，改成"${workspaceFolder}/test/**/*.spec.js" - 务必加
--timeout，否则异步测试超时默认只有 2s，容易误判为卡死 - 不要设
env手动加NODE_OPTIONS=--inspect：VSCode 的node调试器已自动注入，重复会导致端口冲突
Mocha 调试断点不命中？检查 CommonJS/ESM 混用和源码映射
断点灰掉、跳过、停在 node_modules 里，基本是模块系统或 source map 问题。
- 若项目用 ES 模块（
type: "module"在package.json），Mocha 默认不支持，必须改用esm加载器：--loader esm，且program改为node，args加--run和node_modules/mocha/bin/mocha.js - TypeScript 项目必须生成
.js.map文件：确保tsconfig.json有"sourceMap": true，且编译后.js和.js.map在同一目录 - 如果测试文件用了
import但没配ts-node，断点会停在编译后的 JS 上，而不是 TS 源码 —— 此时要确认ts-node/register是否在--require列表里
运行时报错 Cannot find module 'mocha' 或 spawn mocha ENOENT
这不是路径写错，而是 VSCode 启动调试器时没继承 shell 的 PATH，尤其 macOS/Linux 下用 zsh/fish、Windows 下用 Git Bash 时常见。
- 别用
program: "mocha"，永远用绝对路径或node_modules相对路径（如上例） - 如果非要用全局
mocha，在launch.json里加"runtimeExecutable": "npx"，然后"args"改成["mocha", "${file}"] - Windows 用户注意：CMD 和 PowerShell 对引号、空格处理不同，建议统一用
terminal.integrated.defaultProfile.windows设为Command Prompt，并避免路径含中文或空格 - 报错信息里出现
ENOENT却能手动在终端跑通？说明 VSCode 没读取你的 shell 配置（~/.zshrc等），此时应重启 VSCode（不是窗口），让它重载环境变量
真正麻烦的是混合了 Babel、ESBuild、Vitest 或自定义测试 runner 的项目 —— 那些场景下，mocha 只是壳，实际执行链路已经绕开了标准入口。这时候得看构建产物怎么落地，而不是死磕 launch.json。
