根本原因是node.js未正确加入系统path：windows需重装并勾选“add to path”或手动添加安装路径，macos/linux需确保nvm初始化语句写入shell配置文件；vscode内置调试器无需额外插件，验证方式为系统终端中node -v和npm -v均能正常输出。
node -v 和 npm -v 报错，VSCode 调试直接失败
这不是 VSCode 的问题，而是 Node.js 根本没进系统 PATH。调试器启动时会调 npm 找脚本、调 node 启进程，这两个命令在系统终端里都跑不通，VSCode 就连“尝试连接”这一步都跳不过去。
- Windows 安装时必须勾选
Add to PATH；漏了就手动把C:\Program Files\nodejs（或你实际安装路径）加进系统环境变量Path，然后关掉所有终端窗口重开 - Windows 别装在含中文或空格的路径下（比如
D:\我的软件\nodejs），npm会静默失败，不报错但不工作 - macOS/Linux 用
nvm的，确认source ~/.nvm/nvm.sh已写入~/.zshrc或~/.bash_profile，新开终端执行which node看是否输出路径
不需要装任何 Node.js 插件
VSCode 自带 Node.js 调试支持，Node.js Extension Pack、Debugger for Node.js 这类插件早在 2024 年后就过时了，装了反而可能覆盖内置逻辑，导致断点不命中或 Cannot find runtime 'node'。
- 验证方式：新建
index.js，写console.log('ok');，按Ctrl+Shift+P（macOS 是Cmd+Shift+P），输入Debug: Open Configuration→ 选Node.js → Current File - 生成的
.vscode/launch.json里若出现"type": "pwa-node"，说明是新版内置调试器，没问题；若看到"type": "node"且request是launch，也正常 - 只要
node -v和npm -v在系统终端里能跑通，F5 就能断点调试，其余全是干扰项
launch.json 配置踩坑最多的地方
默认生成的 "program": "${file}" 只适合单文件快速验证，一上真实项目就容易卡住——比如你想调试 npm start 或用 nodemon，直接改 program 字段是错的。
- 要跑
npm start：把"program"改成"npm"，"args"设为["start"]，并加上"console": "integratedTerminal"，否则终端输出看不到 - 要用
nodemon热重载：不能在launch.json里直接调它。必须先在终端手动运行nodemon --inspect-brk index.js，再配一个attach模式："type": "node"、"request": "attach"、"port": 9229（nodemon默认端口） - 如果项目入口不是当前文件（比如
src/server.js），别硬改${file}，直接写死路径："program": "${workspaceFolder}/src/server.js"
调试能跑通，但 console.log 不见输出
常见于 Express 或其他监听端口的服务，启动后立即返回控制权，VSCode 调试器以为程序结束了，自动退出——其实服务还在后台跑，只是你没看到日志。
- 加一行
process.stdin.resume();在文件末尾，防止进程退出；或者用setTimeout(() => {}, 10000)拖住进程几秒，方便观察 - 更稳妥的做法：在
launch.json中加"stopOnEntry": false和"console": "integratedTerminal"，确保日志打到 VSCode 内置终端里 - Express 启动后提示
Server running on http://localhost:3000，但终端没刷新？检查是否用了nodemon却没配attach模式，此时日志其实在外部终端，VSCode 里看不到
node 和 npm 在系统层面是否可用——这点被跳过一次，后面所有调试行为都会变成黑盒。
