vscode调试nestjs失败90%因未走编译后路径——必须用node执行dist/main.js而非ts-node运行src/main.ts，launch.json需指向dist/main.js并配置正确sourcemap、outfiles及tsconfig.json，禁用start:dev。
VSCode 调试 NestJS 失败，90% 是因为没走编译后路径——它根本没在跑 dist/main.js，而是在用 ts-node 直接执行 src/main.ts。Node.js 调试器只认 JavaScript + sourceMap，不支持 ts-node 的运行时编译，断点必然失效。
launch.json 必须指向 dist/main.js，不能用 ts-node 启动
VSCode 的 Node.js 调试器无法正确映射 ts-node 动态生成的代码行。哪怕你写了 "runtimeArgs": ["run", "start:debug"]，只要 package.json 里 start:debug 实际执行的是 ts-node -r tsconfig-paths/register src/main.ts，断点就会变空心、悬停显示“未绑定”。
- ✅ 正确做法：
package.json中定义"start:debug": "nest build && node --inspect-brk dist/main.js" - ✅ 对应的
launch.json配置中：runtimeExecutable设为"node"，runtimeArgs设为["--inspect-brk", "${workspaceFolder}/dist/main.js"] - ❌ 错误配置示例：
"runtimeExecutable": "npm"+"runtimeArgs": ["run-script", "start:debug"]—— 如果脚本本身没编译，就白搭
tsconfig.json 的 sourceMap 和 outDir 必须严格匹配
VSCode 调试器靠 sourceMap 把 dist/main.js 的执行位置反向定位到 src/main.ts。只要其中一环断开，整个映射就崩了。
- ✅
tsconfig.json中必须同时存在："sourceMap": true和"outDir": "dist" - ✅
outFiles在launch.json中必须写成["${workspaceFolder}/dist/**/*.js"]—— 漏掉**就找不到dist/users/users.controller.js这类嵌套路径下的文件 - ⚠️ 注意：如果启用了
"incremental": true但没清缓存，旧的.js.map文件可能残留，调试器会加载错误映射；验证方法是打开任意dist/**/*.js，末尾找//# sourceMappingURL=xxx.js.map，确认该文件真实存在且内容可读
npm run start:dev 不能用于调试
npm run start:dev 底层依赖 nodemon 或 ts-node-dev，它们会反复 kill & restart 进程。Node.js 的 --inspect 端口在进程退出时立即释放，VSCode 调试器连不上新进程，表现为“改完代码服务重启了，但所有断点全灰”。
- ✅ 调试阶段请彻底停用
start:dev，改用npm run start:debug（确保它执行的是编译后代码） - ⚠️ Windows 上若报
Cannot connect to runtime process，可能是防火墙拦截了9229端口，或--inspect绑定127.0.0.1与 VSCode 尝试连接localhost存在 loopback 解析差异 - ? 临时解法：把启动命令改成
node --inspect=0.0.0.0:9229 dist/main.js，并在launch.json中显式指定"address": "0.0.0.0"
tsconfig.json 缺失或配置错会导致补全/跳转失效
VSCode 的 TypeScript 语言服务需要明确配置才能解析 src/**/* 下的类、装饰器和 provider 关系。没有它，import UserController 不出补全，Ctrl+Click 跳不到控制器，@Body() dto: CreateUserDto 参数也没提示。
- ✅
tsconfig.json根目录必须存在，且含"include": ["src/**/*.ts"]（不能只写["src/**/*"]） - ✅
"compilerOptions"中必须有"moduleResolution": "node"和"esModuleInterop": true - ✅ 所有被
@Module()引用的 service/controller 必须在当前文件顶部import，且导出方式为export class UsersService（不是export default class） - ⚠️ 如果用了路径别名（如
@/common），baseUrl必须设为"."，paths要严格匹配nest build实际输出路径（例如"@/*": ["src/*"]）
最常被忽略的一点：改完 tsconfig.json 后必须手动按 Ctrl+Shift+P → 输入 Restart TS server，否则补全和跳转不会更新。调试器能连上、断点能命中，只是第一步；类型上下文没加载对，连 @Body() 参数都推导不出来，才是真正卡住开发节奏的地方。
