VSCode调试Mocha失败主因是program未指向_mocha、sourceMap未对齐或异步超时过短；program必须设为"${workspaceFolder}/node_modules/mocha/bin/_mocha"，TS项目需加--require ts-node/register，且args中必须显式配置--timeout。
VSCode 调试 Mocha 测试失败，90% 不是代码写错了，而是 program 指向了错误入口、sourceMap 没对齐，或者异步测试根本没等够时间就超时退出。
为什么 describe 报错“is not defined”
这不是 Mocha 没装好，而是 VSCode 的 Node 调试器直接执行了测试文件，绕过了 Mocha 的运行时环境——describe、it 这些全局函数根本没被注入。
-
program必须设为"${workspaceFolder}/node_modules/mocha/bin/_mocha"，绝不能是"${file}"或"mocha" - TypeScript 项目必须在
args里加--require ts-node/register，否则.ts文件会被 Node 原生执行，语法报错或describe未定义 - ESM 项目（
package.json含"type": "module"）要改用"program": "node"+"runtimeArgs": ["--loader", "ts-node/esm"]+"args": ["node_modules/mocha/bin/mocha.js"]
launch.json 中 program 和 args 怎么配才跑得通
VSCode 的 Node 调试器本质是启动一个 node 进程，所以 program 必须指向可执行 JS 入口（即 _mocha），所有测试路径、参数都得塞进 args。
-
program固定为："${workspaceFolder}/node_modules/mocha/bin/_mocha"（跨平台稳定，避开.cmd/.sh解析问题） -
args第一项必须是测试路径，例如："${file}"（当前文件）或"${workspaceFolder}/test/**/*.spec.js" - 务必加
--timeout "5000"（默认仅 2000ms，数据库查询或setTimeout(3000)直接超时） - 需要递归扫描子目录时，加
--recursive；TS 项目加--require ts-node/register
断点灰掉或不命中，到底该查什么
你在 src/index.ts 打的断点没反应，不是 VSCode 坏了，而是它正在调试 dist/index.js，却找不到或映射错了 dist/index.js.map。
-
tsconfig.json必须开启"sourceMap": true，且"outDir"和"rootDir"配置合理（如"outDir": "./dist", "rootDir": "./src"） -
launch.json中启用"sourceMaps": true，并设置"outFiles"匹配编译输出，例如：["${workspaceFolder}/dist/**/*.js"] - 确保测试文件（如
test/*.spec.ts）也被tsconfig.json的include覆盖到 - 缓存干扰常见：删掉
node_modules/.cache、.ts-node，关掉 VSCode 再重开
异步测试总“跳过”，其实是 timeout 太小
断点刚 hit 就退出，不是调试器问题，是 Mocha 在你还没走到断点前就判定超时、强制结束测试了。
- Mocha 默认异步超时是
2000毫秒，await db.query()或fetch()很容易超 -
args中必须显式加--timeout "15000"（或更高），别依赖默认值 - 避免混用
done()和async/await：比如it('xxx', async () => { done(); })会触发冲突警告 - 用
console.log插在关键异步回调里，确认是否真进了逻辑——有时候断点不命中，只是 Promise 还没 resolve
最易被忽略的是三处对齐：Node.js 版本 ≥ 14、program 指向 _mocha 而非测试文件、sourceMap 路径在 tsconfig.json 和 launch.json 中完全一致。少一个，断点就失效，describe 就 undefined。
