vscode调试mocha失败主因是program未指向_mocha、sourcemap未对齐或mocha环境未加载；program必须设为"${workspacefolder}/node_modules/mocha/bin/_mocha"，ts项目需加--require ts-node/register，异步测试必配--timeout，sourcemap须在tsconfig.json和launch.json中严格匹配。
VSCode 调试 Mocha 失败，基本不是代码问题，而是 program 指向错误、sourceMap 没对齐，或 Node.js / Mocha 环境没被真正加载。
launch.json 的 program 必须指向 _mocha，不能是 mocha 或测试文件
VSCode 的 Node.js 调试器不走 shell 环境，写 "program": "mocha" 会报 spawn mocha ENOENT；写 "program": "${file}" 更危险——Node 直接执行测试文件，Mocha 根本没启动，describe 和 it 全部未定义。
-
program应固定为："${workspaceFolder}/node_modules/mocha/bin/_mocha"（跨平台稳定，绕过.cmd/.sh解析） - 测试路径必须放在
args里，例如："${file}"（当前文件）或"${workspaceFolder}/test/**/*.spec.js" - 如果项目用 TypeScript，
args中必须加--require ts-node/register，否则.ts文件被 Node 原生执行，直接报语法错误 - ESM 项目（
package.json含"type": "module"）要改用："program": "node"+"runtimeArgs": ["--loader", "ts-node/esm"]+"args": ["node_modules/mocha/bin/mocha.js"]
异步测试不命中断点？大概率是 --timeout 没配或配太小
Mocha 默认异步超时仅 2000ms，一个数据库查询、setTimeout(3000) 或网络请求就直接退出，断点刚 hit 就结束，看起来像“跳过”。
- 务必在
args中显式加--timeout，推荐设为"5000"或更高（如"15000"） - 避免混用
done()和async/await：比如it('xxx', async () => { done(); })会触发 Mocha 冲突警告 - 用
console.log在关键异步回调里打点，确认是否真进了逻辑——有时候断点不命中，只是 Promise 还没 resolve
TypeScript 项目断点灰掉？检查 sourceMap 三件套是否全对齐
你在 src/index.ts 打的断点没反应，不是 VSCode 坏了，而是它正在调试 dist/index.js，却找不到或映射错了 dist/index.js.map。
-
tsconfig.json必须开启："sourceMap": true，且"outDir"和"rootDir"要匹配（如"outDir": "./dist"，"rootDir": "./src"） -
test/*.spec.ts也得在tsconfig.json的"include"里，否则不会生成对应 map 文件 -
launch.json中启用"sourceMaps": true，并设置"outFiles"精确匹配编译输出，例如：["${workspaceFolder}/dist/**/*.js"] - 缓存干扰常见：删掉
node_modules/.cache、.ts-node等目录再试；重启调试会话（不是继续运行），必要时关掉窗口重开
Test Explorer 点 Debug 没反应？别信它自动生成的 launch.json
Test Explorer 的「Debug」按钮本质是启动一个 Node.js 调试会话，但默认不继承项目里的 jest.config.js 或环境变量，容易路径解析失败或 mock 不生效。
- 不要依赖扩展自动生成的
.vscode/launch.json，手动添加配置，确保program和args与命令行可运行的一致 - 确认终端里能跑通：
npx mocha test/foo.spec.js—— Test Explorer 不会帮你装 Mocha，也不会读你没提交的脚本 - Mocha 用户必须装
hbenl.vscode-mocha-test-adapter，且mocha得在node_modules里（不是全局安装） - 装完扩展后重启 VSCode，状态栏右下角应出现 Test 图标；若显示 “No test provider registered”，说明 adapter 没加载成功
最常被忽略的是：TS 项目里 test/ 目录没进 tsconfig.json 的 include，导致测试文件压根没编译、没生成 sourceMap——断点自然永远灰着。
