vscode调试mocha异步测试失败主因是node运行时、mocha启动路径与sourcemap映射三者未对齐；program必须设为"${workspacefolder}/node_modules/mocha/bin/_mocha"，args需含测试路径和--timeout，ts项目必加--require ts-node/register且sourcemap严格匹配。
VSCode 调试 Mocha 异步测试失败，90% 是因为调试器根本没启动 Mocha 环境——describe 报错、断点灰掉、setTimeout 或 Promise 测试秒退，全指向同一个根因：Node 运行时、Mocha 启动路径、sourceMap 映射三者没对齐。
program 必须指向 _mocha，不能是 mocha 或测试文件
VSCode 的 Node.js 调试器不走 shell，写 "program": "mocha" 会直接报 spawn mocha ENOENT；写 "program": "${file}" 更危险——等于让 Node 直接执行测试文件，describe 和 it 根本没被 Mocha 注入全局作用域。
-
program应固定为："${workspaceFolder}/node_modules/mocha/bin/_mocha"（跨平台稳定，避开 Windows.cmd和 macOS/Linux.sh解析差异） - 测试路径必须放在
args里，例如："${file}"（当前文件）或"test/**/*.spec.js"（整个目录） - TS 项目必须加
--require ts-node/register到args，否则.ts文件被 Node 原生执行，直接报语法错误 - ESM 项目（
package.json含"type": "module"）要改用"program": "node"，并配"runtimeArgs": ["--loader", "ts-node/esm"]和"args": ["node_modules/mocha/bin/mocha.js", ...]
异步测试必配 --timeout，默认 2000ms 远不够用
Mocha 默认异步超时是 2000 毫秒，但一个 setTimeout(3000)、数据库查询或 HTTP 请求很容易就超了。结果就是断点刚 hit 就退出，或者测试显示 “passed” 但实际逻辑根本没走完。
微软正式发布 Visual Studio Code 1.118 版本 。本次更新重点强化了 AI 开发体验与企业管理能力，其中最引人注目的是新增 Copilot CLI 远程控制功能，允许开发者通过手机或网页远程监控和接管 AI 会话 。同时，为了提高 AI 的运行性价比，新版本优化了令牌缓存策略以降低成本 。此外，1.118 版还引入了 Chronicle 本地历史追踪、TypeScript 7.0 支持以及更严格的企业级访问管控 。
-
args中必须显式包含--timeout，推荐设为"5000"或"15000" - 避免混用
done()和async/await：比如it('xxx', async () => { done(); })会触发 Mocha 冲突警告 - 用
console.log在关键位置打点，确认是否真进了异步回调——有时候断点不命中，只是因为 Promise 还没 resolve
断点不命中？查 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等缓存目录，重启调试会话（不是继续运行），必要时关窗口重开
真正卡住的从来不是语法或断点本身，而是 program、args、sourceMap 这三者的路径和时机是否严丝合缝——漏掉任意一环，describe is not defined 就会准时出现。
