NestJS调试失败主因是源码映射路径不匹配，需正确配置launch.json的outFiles、启用sourceMaps，并确保运行dist/main.js而非ts-node；使用npm run start:debug或attach模式更稳定。
调试 NestJS 时 launch.json 不生效？检查 outFiles 和源映射路径
VSCode 调试 NestJS 项目失败，最常见原因是 TypeScript 编译后路径和调试器找不到对应源码。NestJS 默认用 tsc 编译，生成的 .js 文件在 dist/ 下，但 VSCode 的 Node.js 调试器需要明确告诉它“去哪找原始 .ts 文件”。
-
outFiles必须显式列出编译输出路径，比如["${workspaceFolder}/dist/**/*.js"]，漏掉**就会跳过子目录下的控制器和服务 -
sourceMaps必须为true，且tsconfig.json中"sourceMap": true和"outDir": "dist"要匹配 - 如果用了
nest build --watch或npm run start:dev，它们不走tsc标准流程，调试器无法附加——必须用npm run start:debug这类基于node --inspect的命令
Controller 和 Service 断点不命中？确认运行的是编译后代码，不是 src/ 源文件
NestJS 开发时容易误用 ts-node 直接跑 src/main.ts，这时 VSCode 调试器看到的是 TypeScript 源码，但实际执行的是 ts-node 动态编译结果，断点映射错乱。真正可稳定调试的路径只有一条：先编译，再运行 dist/main.js。
- 确保启动脚本是
node dist/main.js，而不是ts-node src/main.ts - 在
package.json里配好"start:debug": "node --inspect-brk -r ts-node/register src/main.ts"是陷阱——它绕过了dist/，断点常偏移或失效 - Controller 类里的方法断点没反应？大概率因为该 Controller 没被模块
imports或providers注册，Nest 根本没加载它，自然不会执行到那行
修改代码后调试器不自动重启？别依赖 nodemon + --inspect 组合
很多人把 nodemon --exec node --inspect src/main.ts 当成热重载方案，但 Node.js 的 --inspect 端口在进程重启时会释放，VSCode 调试器连不上新进程，表现为“改了代码，服务重启了，但断点全灰了”。
- 正确做法是用 Nest CLI 自带的调试模式：
npm run start:debug（前提是scripts里定义为nest start --debug 9229） - 或者手动组合：
nodemon --exec node --inspect=0.0.0.0:9229 -r ts-node/register src/main.ts，但必须加=0.0.0.0:9229强制端口复用，否则每次重启都换端口 - VSCode 的
attach配置比launch更稳：它不启动进程，只监听已存在的--inspect端口，适合配合npm run start:debug
Windows 上调试报错 Cannot connect to runtime process？检查防火墙和端口权限
尤其在公司内网或装了第三方安全软件的 Windows 机器上，--inspect 默认绑定 127.0.0.1，但 VSCode 调试插件有时会尝试连 localhost 或 0.0.0.0，中间有 DNS 或 loopback 解析差异，导致连接拒绝。
- 把启动命令改成
node --inspect=0.0.0.0:9229 dist/main.js，并确保launch.json的address字段也设为"0.0.0.0" - 检查 Windows 防火墙是否拦截了 9229 端口（哪怕只是本地通信）；临时关闭防火墙测试一次就能定位
- 如果用 WSL2，VSCode 在 Windows 侧调试 WSL2 里的 NestJS，必须用
localhost（WSL2 的 localhost 会自动转发），不能写127.0.0.1或0.0.0.0
真正卡住人的从来不是配置项本身，而是 NestJS 启动链路上多个环节（TS 编译、Node 运行时、调试协议、VSCode 插件）对路径和端口的理解不一致。调通的关键不是堆参数，是确认当前到底在跑哪段代码、调试器连的是哪个进程、源码映射有没有被某层工具悄悄覆盖。
