绝大多数情况应使用launch模式，即VS Code自行启动Node进程并注入调试器；仅当需调试已运行进程（如npm start或Docker内服务）时才用attach模式。
VSCode 调试 Node.js 脚本，**绝大多数情况直接用 launch 模式就行**，不用纠结 attach 或 nodemon 集成——除非你明确需要热重载或复用已有启动命令。
选 launch 还是 attach？看进程谁来启
关键不是“哪个高级”，而是“谁在控制生命周期”：
-
launch：VS Code 自己拉起node进程，适合单次脚本、CLI 工具、API 服务快速验证。断点稳、路径好配、环境干净。 -
attach：Node 进程已由终端（如node --inspect-brk server.js）或 npm script（如"debug": "node --inspect-brk index.js"）启动，VS Code 只连接。适合调试长时运行的服务、或必须走特定启动流程的场景。 - 别混用：比如在
launch配置里把program写成nodemon，VS Code 会尝试直接执行nodemon二进制，而不是让它启动子进程——结果要么报错，要么断点完全不生效。
program 字段必须指向真实可执行的 .js 文件
这是断点不触发的第一大原因。VS Code 不会帮你编译、转译或解析入口，它只认 JS：
用于自动切换项目中适合的node 版本
下载
根据 package.json 中的 engines 字段自动检测 Node.js 版本需求，未安装 nvm 时自动安装并切换至对应版本。支持 Windows、macOS、Linux。适用于 Node.js 项目开发、版本切换和环境配置。
- TS 项目？
program必须是编译后的路径，例如"${workspaceFolder}/dist/server.js"，不是src/server.ts。 - 用
ts-node？可以，但得改runtimeExecutable为ts-node，并确保sourceMaps: true和outFiles配对（否则断点停在 JS 行，和 TS 对不上）。 - ESM 项目？加
"runtimeArgs": ["--loader", "ts-node/esm"]，且确认ts-node已全局或本地安装。 - 路径含空格？不用手动加引号，VS Code 自动处理；但若用了
args数组，每个参数字符串得自己包引号，比如"--port=3001"。
断点变空心？先查 sourceMaps 和 outFiles
空心红点 = VS Code 找不到源码映射关系。不是代码问题，是配置没告诉它“JS 是从哪来的”：
- TypeScript 必须同时满足三件事：
"sourceMap": true在tsconfig.json中开启；"sourceMaps": true在 launch.json 配置里启用；"outFiles": ["${workspaceFolder}/dist/**/*.js"]明确输出路径（路径必须和实际构建产物一致）。 - 如果
.ts文件不在根目录下（比如packages/api/src），还得加"resolveSourceMapLocations": ["${workspaceFolder}/packages/**/src/**", "!**/node_modules/**"]，不然它可能去node_modules里瞎找 map。 - 没配
outFiles，VS Code 就不知道该把dist/index.js的第 42 行映射回src/index.ts的哪一行——断点只能打在 JS 上，且大概率偏移。
环境变量和端口冲突最容易被忽略
看似和断点无关，实则常导致调试静默失败：
-
env不继承终端：即使你在终端里export PORT=4000，VS Code 调试器默认看不到。必须显式写进 launch.json 的"env": {"PORT": "4001"}，尤其避免和本地已运行的npm run dev端口撞车。 -
skipFiles别乱设宽泛路径：比如"${workspaceFolder}/node_modules/**/*.js"可能跳过你依赖里关键的调用链（像knex的 query 方法），导致断点“跳过”而非“不触发”。真要跳过，用更精确的"<node_internals>/**"</node_internals>就够了。 - macOS/Linux 下 PATH 不生效？检查 VS Code 是不是从桌面图标启动的——它可能没加载 shell 的
PATH。在 VS Code 终端里跑node -v失败，就得在.vscode/settings.json里补全"terminal.integrated.env.osx"。
最麻烦的从来不是怎么设断点，而是断点设完后，VS Code 根本没连上那个 Node 进程——所以每次改完 launch.json，务必看底部状态栏有没有「调试正在运行」，再打开「调试控制台」确认有没有 Debugger attached. 日志。
