能跑 node -v 且 VSCode 里按 F5 能断点调试才算配好；需确保内置终端中 node -v 和 npm -v 均输出版本号，Windows 漏勾“Add to PATH”或 macOS/Linux 未配置 nvm 初始化均会导致环境变量未继承，launch.json 中 program 字段应设为 "${file}"（单文件）或 "${workspaceFolder}/index.js"（固定入口），调试 nodemon 需用 attach 模式并启用 autoAttachChildProcesses 支持子进程。

能跑 node -v 且 VSCode 里按 F5 能断点调试，才算配好；其余全是可选项。

终端里 node -v 成功，但 VSCode 内置终端报错

这不是 VSCode 故障，是它没继承 shell 的环境变量。Windows 用户重装 Node.js 时漏勾了 “Add to PATH”，macOS/Linux 用户用 nvm 却没把 source ~/.zshrc 写进配置文件，都会导致这个问题。

• Windows：打开“系统属性 → 高级 → 环境变量”，把 C:\Program Files\nodejs 加进“系统变量”的 PATH，然后彻底关掉所有 VSCode 窗口再重开
• macOS/Linux：确认 ~/.zshrc（或 ~/.bash_profile）里有 export NVM_DIR="$HOME/.nvm" 和 source ~/.nvm/nvm.sh，改完后在终端执行 source ~/.zshrc，再用 code . 启动 VSCode（别从 Dock 点）
• 验证方式只有一种：在 VSCode 内置终端（Ctrl + `）里敲 node -v 和 npm -v，两个都输出版本号才算过关

launch.json 里 program 字段写什么

默认生成的 "program": "${workspaceFolder}/app.js" 是个陷阱——项目没 app.js 就直接报错。实际开发中，入口文件名千差万别，硬编码路径只会卡住你。

• 单文件调试：设为 "program": "${file}"，这样无论当前打开的是 index.js 还是 server.js，按 F5 都能跑
• 固定入口：明确知道主文件是 index.js，就写 "program": "${workspaceFolder}/index.js"，别用相对路径如 ./index.js
• 调试 npm start：把 "program" 改成 "npm"，加 "args": ["start"] 和 "console": "integratedTerminal"，否则看不到日志输出
• 务必手动保存文件再调试：F5 不会自动存盘，未保存的修改不会生效

想用 nodemon 热重载，但断点不命中

VSCode 调试器不支持热替换，直接在 launch.json 里调 nodemon 会失败。必须走 attach 模式，让调试器连上已启动的进程。

用于自动切换项目中适合的node 版本

根据 package.json 中的 engines 字段自动检测 Node.js 版本需求，未安装 nvm 时自动安装并切换至对应版本。支持 Windows、macOS、Linux。适用于 Node.js 项目开发、版本切换和环境配置。

下载

• 先在终端手动运行：nodemon --inspect-brk index.js（注意加 --inspect-brk，不是 --inspect）
• 再配置 launch.json："type": "node"、"request": "attach"、"port": 9229（和 nodemon 默认端口一致）
• 如果端口被占，改用 nodemon --inspect-brk=9230 index.js，同时把 launch.json 中的 port 改成 9230
• nodemon 必须全局安装且 VSCode 终端能识别：npm install -g nodemon 后，在 VSCode 终端里运行 nodemon -v 验证

Worker Threads 或 fork() 子进程断点失效

默认调试器只 attach 主进程，子进程完全被忽略。必须显式启用子进程自动附加，并确保子进程自己开了调试端口。

• 在 launch.json 里加 "autoAttachChildProcesses": true（布尔值，不是字符串）
• Worker 构造时传参：new Worker('./worker.js', { execArgv: ['--inspect-brk=9229'] })
• child_process.fork() 也得带参数：fork('./sub.js', [], { execArgv: ['--inspect-brk=9230'] })
• 主进程 launch 配置里加 "runtimeArgs": ["--inspect-brk"]，端口要和子进程一致或留空让 Node 自选
• 多个 Worker 共用同一端口会导致只连上第一个——要么分配唯一端口，要么干脆不指定端口让 Node 动态分配

最常被跳过的一步是：没在 VSCode 终端里亲手敲一遍 node -v 和 npm -v。只要这俩不行，后面所有配置都是白忙。