能跑 node -v 是硬门槛，否则所有 launch.json 配置无效；vscode 未加载 shell 初始化文件导致 path 缺失 node 路径，需手动配置并重启 vscode；program 字段必须指向正确 js 入口文件，typescript 项目需 sourcemap 且 outfiles 匹配 dist 目录；esm 项目须声明 "type": "module"；调试应使用 attach 模式而非直接运行 nodemon；windows 需检查防火墙是否拦截 9229 端口。
能跑 node -v 是硬门槛，否则所有 launch.json 配置都是空中楼阁。
终端能用 node，但 VSCode 里报 command not found
这不是 VSCode 配置问题，是它没加载你的 shell 初始化文件（比如 ~/.zshrc 或 ~/.bash_profile），PATH 里压根没有 node 路径。
- macOS/Linux：在终端运行
which node，把输出路径（如/opt/homebrew/bin/node）加进~/.zshrc的export PATH="...:$PATH"；改完后必须 彻底退出 VSCode 进程，再从终端执行code .启动 - Windows：打开系统环境变量，确认
C:\Program Files\nodejs\在“系统变量 > PATH”中；没加就手动添，或者重装 Node.js 并务必勾选 “Add to PATH” - 验证方式：VSCode 内置终端（
Ctrl + `）里直接输node -v—— 没输出就别碰launch.json，全是白搭
launch.json 的 program 字段总指向错误文件
program 是调试器找入口的唯一依据，写错路径、混用源文件和编译后文件、忽略工作目录，断点就永远停不住。
- 单文件测试可用
"program": "${file}"；NestJS 项目必须显式写绝对路径，比如"program": "${workspaceFolder}/src/main.ts"（前提是用ts-node）或"program": "${workspaceFolder}/dist/main.js"（前提是已编译） - TypeScript 项目：
program必须指向.js文件（如dist/main.js），不能指src/main.ts；同时tsconfig.json里得有"sourceMap": true，且.js.map和.js在同一目录 - ESM 项目：
package.json必须含"type": "module"，否则调试器按 CommonJS 解析，import路径全错 - 加
"cwd": "${workspaceFolder}"显式声明工作目录，避免require('./config')因路径解析失败而报Cannot find module
用 npm run start:debug 启动时断点不生效
常见现象是断点变灰色、提示 “unbound breakpoint”，根源通常不是代码问题，而是调试模式与运行逻辑不匹配。
- 确保
package.json中start:debug脚本启用--inspect，例如："start:debug": "node --inspect-brk -r ts-node/register src/main.ts"；注意端口要和launch.json中port字段一致（默认9229） - 别用
nodemon直接配runtimeExecutable——它会接管进程启动，VSCode 无法稳定附加；改用attach模式：终端先跑npm run start:debug，再在launch.json新增一个"request": "attach"配置连过去 - 如果用了
tsconfig-paths，launch.json的env里必须加"TS_NODE_PROJECT": "tsconfig.json"，否则路径别名失效 - 调试控制器时，
main.ts入口断点几乎没用；真正要调试业务逻辑，断点应设在@Get()装饰器下的函数体、守卫或服务方法内部
NestJS 调试最易被忽略的细节
很多人卡在断点不命中，最后发现是 outFiles 没配对、sourceMap 路径不匹配，或者根本没运行编译后的 dist/ 代码。
-
launch.json中必须显式配置"outFiles": ["${workspaceFolder}/dist/**/*.js"]，漏掉**就跳过子目录下的控制器和服务 - 确保启动的是
node dist/main.js，而不是ts-node src/main.ts；后者会让 VSCode 看到 TypeScript 源码，但实际执行的是动态编译结果，断点映射错乱 - Windows 上若报
Cannot connect to runtime process，检查防火墙是否拦截了9229端口；临时关闭防火墙测试一次就能定位 - 修改代码后调试器不自动重启？别依赖
nodemon --exec node --inspect组合——Node.js 的--inspect端口在进程重启时会释放，VSCode 连不上新进程
