vscode调试node.js必须满足三个前提：一是在内置终端（ctrl+`）中能执行node -v和npm -v；二是launch.json需显式配置"type": "node"、"runtimeexecutable"（nvm/fnm路径）和"env"（手动加载环境变量）；三是typescript项目须在launch.json中启用"sourcemaps": true并正确设置"outfiles"和"resolvesourcemaplocations"。
node 命令必须在 VSCode 内置终端里能直接执行，否则所有调试配置都无效——这是最常被跳过的前提。
先确认 node 和 npm 在终端可用
别只在系统终端里验证，必须在 VSCode 自带的终端（Ctrl + `）里运行：node -v 和 npm -v。如果报错“command not found”，说明 VSCode 没读到你改好的 PATH。
- Windows 用户重点检查安装路径：避开
C:\Program Files\nodejs这类含空格或中文的路径 - macOS/Linux 用户常见问题是 shell 启动 VSCode 时没继承 PATH，比如用 zsh 安装了 node，但 VSCode 是从 Dock 启动的——它根本不知道
which node输出的路径 - 改完环境变量后，必须完全退出 VSCode（不是关窗口，是 Quit），再重新打开
launch.json 必须显式写对这三项
VSCode 自动生成的模板经常漏掉关键字段，导致断点不触发、process.env 为空、日志看不到输出。
-
"type": "node"：别手写"pwa-node"，尤其老项目或 CI 场景下 fallback 不稳定 -
"runtimeExecutable"：当你用nvm或fnm切换版本时，必须填绝对路径，比如/Users/you/.nvm/versions/node/v20.15.0/bin/node；不写就按 PATH 找，而 PATH 里的node可能和终端里看到的不是同一个 -
"env"：.env文件不会自动加载，开发环境变量如NODE_ENV、PORT必须手动写进配置，例如："env": {"NODE_ENV": "development", "PORT": "3001"}
调试 Express/Koa 等 Web 服务时，别让断点卡在启动前
默认 request: "launch" 模式会在入口文件第一行就暂停，但 Web 服务真正执行路由逻辑是在 app.listen() 之后——你打的断点根本没机会命中。
- 正确做法是加
"args": ["--inspect-brk"]，让 Node 启动即中断，等 VSCode 附加后再继续执行 - 如果用了
nodemon，不要直接替换runtimeExecutable为nodemon；要配成："runtimeExecutable": "${workspaceFolder}/node_modules/.bin/nodemon"，并加"runtimeArgs": ["--inspect-brk", "${workspaceFolder}/app.js"] - 避免用
spawn()启动子进程——它不自动暴露调试端口；改用fork()并传execArgv: ['--inspect=9230']，否则autoAttachChildProcesses: true也抓不到
TypeScript 项目里断点停在 .js 文件？源码映射链断了
VSCode 不会读 tsconfig.json 里的 "sourceMap": true，必须在 launch.json 里双重声明。
- 编译时确保生成
.map文件：tsc --sourceMap或tsconfig.json中设"sourceMap": true -
launch.json里加："sourceMaps": true和"outFiles": ["./dist/**/*.js"]（路径要和实际输出目录一致） - 如果
.ts文件不在根目录下（比如在packages/foo/src），还得加"resolveSourceMapLocations"显式放行：["${workspaceFolder}/packages/**/src/**", "!**/node_modules/**"]
autoAttachChildProcesses: true 这个开关只对 child_process.fork() 和 Worker 生效，且 Worker 必须自己带 --inspect-brk 参数，否则 VSCode 根本不知道它存在。
