能输出版本号说明环境已就绪；否则问题出在系统path或vscode未继承shell环境，需关掉所有窗口后从终端执行code .启动以确保加载最新配置。

直接在 VSCode 内置终端里运行 node -v 和 npm -v，能输出版本号就说明环境已就绪；如果报错，问题一定出在系统 PATH 或 VSCode 继承的 shell 环境上，不是插件或配置的问题。

为什么终端里能跑，VSCode 里却报 “command not found”？

VSCode 的集成终端（Ctrl + `）默认继承你当前 shell 的环境变量，但有时会“卡住”旧状态：

• macOS/Linux：改过 ~/.zshrc 或 ~/.bash_profile 后没 source，或者 VSCode 是从 Dock/桌面图标启动的（没走 shell），导致 PATH 未更新
• Windows：Node.js 安装时没勾选 “Add to PATH”，或手动添加后没重启 VSCode
• M1/M2 Mac 用 Homebrew 安装但未 brew link node，which node 返回空

验证方式：关掉所有 VSCode 窗口，从终端执行 code . 启动，再试 node -v。这样能确保它读到最新 shell 配置。

launch.json 里要不要配 node.runtimePath？

绝大多数情况不用——只要终端里 node -v 能跑通，VSCode 调试器就会自动调用同一个 node 可执行文件。只有两种场景才需要显式设置：

Rydberg Agent Node

使用一条命令部署ProbeChain Rydberg测试网代理节点。自动注册为Agent(NodeType=1)，免gas，支持macOS/Linux/Windows。触发词：/r

下载

• 你用 nvm 管理多个 Node 版本，且 VSCode 启动时默认用了非预期版本（比如项目要求 v18，但终端默认是 v20）
• VSCode 无法正确解析软链接（如某些 Linux 发行版的 /usr/bin/node 指向 /etc/alternatives/node），这时设成 which node 输出的绝对路径更稳

配置项写法："node.runtimePath": "/opt/homebrew/bin/node"（macOS）或 "node.runtimePath": "C:\Program Files\nodejs\node.exe"（Windows）

调试启动失败，怎么快速判断是不是环境问题？

别急着改 launch.json，先做三件事：

• 打开 VSCode 内置终端，执行 node --version 和 npm --version —— 必须有输出
• 执行 node ${workspaceFolder}/app.js（把 app.js 换成你的真实入口文件）—— 看是否能直接跑起来
• 检查当前打开的文件夹是不是项目根目录（即 package.json 所在目录）—— ${workspaceFolder} 就是这里，写错路径全白搭

如果前三步都 OK，那问题才在配置；如果第二步就报 Cannot find module，说明 require() 路径或 type: "module" 设置有问题，和环境无关。

真正容易被忽略的是：VSCode 不会自动感知你刚装的 Node.js，也不会刷新已启动实例的 PATH。哪怕你重装了 Node.js，也得彻底退出 VSCode 再重开——这是最常被跳过的一步。