必须先确保 node -v 和 npm -v 在系统终端中能正常执行，否则 VSCode 内置终端调试必失败；常见原因是 Node.js 未加入 PATH、Windows 安装路径含中文/空格，或 macOS/Linux 未正确配置 nvm 环境。
node -v 和 npm -v 必须在系统终端里能跑通
VSCode 里点开内置终端就直接失败？别急着配插件或改 launch.json，先关掉 VSCode，打开系统自带终端（Windows 是 cmd/PowerShell，macOS/Linux 是 Terminal/iTerm），执行：
-
node -v—— 应输出类似v20.15.0 -
npm -v—— 应输出类似10.9.2
任一命令报“不是内部或外部命令”，说明 Node.js 没进系统 PATH。LTS 安装时漏勾 Add to PATH 是最常见原因；Windows 用户若装在 D:\我的软件\nodejs 这类含中文或空格路径下，npm 会静默出错；macOS/Linux 用 nvm 的，确认 source ~/.nvm/nvm.sh 已写入 ~/.zshrc 或 ~/.bash_profile，且新开终端已加载。
用 npm init -y 生成 package.json 就算工程建好了
不用模板、不装脚手架，纯手动建工程最快。步骤极简：
- 新建空文件夹，用 VSCode 打开它（不是“打开文件”，是“打开文件夹”）
- 按
Ctrl+`（macOS 是Cmd+`）唤出内置终端 - 执行
npm init -y—— 一行命令生成标准package.json，含main字段默认指向index.js - 手动创建
index.js，写console.log('ready');即可验证
此时就是合法的 Node 工程：有 package.json、能 npm install、能 npm run start（需在 scripts 里加 "start": "node index.js"）。
launch.json 里 “program”: “${file}” 只适合单文件调试
刚建好的工程如果想 F5 调试 index.js，直接按 Ctrl+Shift+P → 输入 Debug: Open Configuration → 选 Node.js → Current File，VSCode 自动生成 .vscode/launch.json，里面关键字段是：
使用一条命令部署ProbeChain Rydberg测试网代理节点。自动注册为Agent(NodeType=1)，免gas，支持macOS/Linux/Windows。触发词：/r
{
"configurations": [{
"type": "node",
"request": "launch",
"name": "Launch Program",
"program": "${file}"
}]
}
这没问题，但注意：${file} 指的是当前活动标签页的文件，不是项目入口。如果后续你把入口改成 src/app.js 或用了 npm start，就得手动改配置：
- 调试
npm start：把"program"改成"npm"，加"args": ["start"]，再加"console": "integratedTerminal"，否则看不到日志 - 调试
nodemon：不能设"program": "nodemon"—— VSCode 调试器不支持热替换，必须用attach模式：先终端运行nodemon --inspect-brk index.js，再在launch.json中设"request": "attach"和"port": 9229
不要装 Node.js Extension Pack 这类过时插件
VSCode 自带 Node.js 调试支持，从 1.70 版本起，Debugger for Node.js 和 Node.js Extension Pack 已被官方标记为“deprecated”。装了反而可能和内置调试器冲突，导致断点不命中、Cannot find runtime 'node' 等错误。
真正需要的只有：
-
ESLint（配合eslint-config-prettier关闭冲突规则） -
Prettier（设editor.formatOnSave为 true） -
Path Intellisense（补全require()或import路径）
其它所谓“Node.js 开发必备插件”，基本是旧文档遗留，现在纯属干扰项。
真正的门槛不在 VSCode 设置，而在 node 命令能否被系统全局识别——这点卡住，后面所有调试、运行、依赖安装都会无声失败。盯着 node -v 和 npm -v 在系统终端里跑通，比折腾 launch.json 重要十倍。
