vscode调试nestjs失败主因是未走编译路径，必须运行dist/main.js而非ts-node src/main.ts；需配置launch.json指向dist、启用sourcemap、使用npm run start:debug并确保模块正确注册。
VSCode 调试 NestJS 项目失败，90% 是因为没走编译后路径，而是直接跑了 ts-node src/main.ts —— 这种方式 VSCode 的 Node.js 调试器无法正确映射断点，console.log 都比它可靠。
launch.json 必须指向 dist/main.js，不能用 ts-node 启动
VSCode 的 Node.js 调试器只认编译后的 JavaScript + sourceMap，不支持 ts-node 的运行时编译。哪怕你写了 "runtimeArgs": ["run", "start:debug"]，如果 package.json 里 start:debug 实际是 ts-node -r tsconfig-paths/register src/main.ts，那断点一定失效。
- ✅ 正确做法：在
package.json中定义"start:debug": "node --inspect-brk -r ts-node/register src/main.ts"是陷阱；应改为"start:debug": "nest build && node --inspect-brk dist/main.js" - ✅ 对应的
launch.json配置中runtimeExecutable设为"node"，runtimeArgs设为["--inspect-brk", "${workspaceFolder}/dist/main.js"] - ❌ 错误现象：断点变空心、灰色、悬停显示 “未绑定”，终端没输出
Debugger listening on ws://... - ⚠️ 注意：
outFiles必须写成["${workspaceFolder}/dist/**/*.js"]，漏掉**就找不到dist/users/users.controller.js这类嵌套路径下的文件
tsconfig.json 的 sourceMap 和 outDir 必须严格匹配
VSCode 调试器靠 sourceMap 文件把 dist/main.js 里的代码行反向定位到 src/main.ts。只要其中一环断开，整个映射就崩了。
- ✅
tsconfig.json中必须同时存在："sourceMap": true和"outDir": "dist" - ✅ 确保没有其他
tsconfig.build.json或自定义构建脚本覆盖了这些设置 - ❌ 常见坑：启用了
"incremental": true但没清缓存，导致旧的.js.map文件残留，调试器加载了错误映射 - ? 验证方法：打开任意一个
dist/**/*.js文件，末尾找//# sourceMappingURL=xxx.js.map，确认该.map文件真实存在且内容可读
npm run start:dev 不能用于调试，它和 --inspect 不兼容
npm run start:dev 底层依赖 nodemon 或 ts-node-dev，它们会反复 kill & restart 进程，而 Node.js 的 --inspect 端口在进程退出时立即释放。VSCode 调试器连不上新进程，表现为“改完代码服务重启了，但所有断点全灰”。
- ✅ 调试阶段请彻底停用
start:dev，改用npm run start:debug（确保它执行的是编译后代码） - ✅ 如果非要热重载+调试，可用
nest build --watch+ 单独开一个终端跑node --inspect-brk dist/main.js，再在 VSCode 中用attach模式连接 - ⚠️ attach 模式下
launch.json要设"request": "attach"，并明确指定"port": 9229（或你启动时指定的端口） - ❌ 不要混用：
"request": "launch"和"request": "attach"配置不能共存于同一配置项
Windows 上连不上 debugger？检查 0.0.0.0 绑定和防火墙
Windows 默认安全策略常拦截 --inspect 的 loopback 流量，尤其公司内网或装了 360/火绒等软件的机器，127.0.0.1:9229 可能被 DNS 解析或防火墙策略阻断。
- ✅ 启动命令改成
node --inspect=0.0.0.0:9229 dist/main.js - ✅
launch.json中加字段："address": "0.0.0.0"，否则 VSCode 默认连localhost - ✅ 临时关闭 Windows 防火墙测试，或放行端口 9229（TCP 入站）
- ? 提示：终端输出出现
Debugger listening on ws://0.0.0.0:9229/...才算真正生效
最易被忽略的一点：NestJS 模块注册不是“生成即生效”。用 nest g controller users 生成后，若没手动把 UsersModule 加进 AppModule 的 imports，或者 UsersController 没列在对应模块的 controllers: [] 里，那这个控制器根本不会被加载——你打再多断点，也永远等不到它执行。
