根本原因是系统PATH未包含Node.js可执行路径，VSCode终端未继承shell配置导致环境变量缺失；需先在系统终端用which node和echo $PATH验证安装路径与环境变量，再通过命令行启动code .、设置terminal.integrated.env.osx或手动source配置文件修复。

终端里输 node 报错：command not found 怎么办

根本原因是系统 PATH 没包含 Node.js 的可执行路径，VSCode 的集成终端默认继承系统 shell 环境，但有时不会自动加载你 shell 配置文件（如 ~/.zshrc 或 ~/.bash_profile）里的 PATH 修改。

• 先在系统终端（不是 VSCode 里）运行 which node，确认 Node 安装位置，比如输出 /usr/local/bin/node
• 再运行 echo $PATH，看该路径是否在其中；若不在，说明 shell 配置未生效
• VSCode 启动方式影响环境继承：用命令行启动（code .）通常能正确加载 shell 配置；直接双击图标启动则可能丢失自定义 PATH
• 临时解决：在 VSCode 终端里手动执行 source ~/.zshrc（macOS / Linux）或 RefreshEnv（PowerShell）
• 长期方案：修改 VSCode 设置，在 settings.json 中加 "terminal.integrated.env.osx": { "PATH": "/usr/local/bin:${env:PATH}" }（macOS 示例，Windows 用 env.windows，Linux 用 env.linux）

node 能跑，但 npm 找不到或版本旧

Node.js 安装包自带 npm，但某些第三方安装方式（如 Homebrew、nvm 或 Windows MSI 自定义安装）可能导致 npm 未正确链接或被覆盖。

OC SSH Tunnel Node Recovery

诊断并恢复通过 SSH 隧道连接的 OpenClaw 节点。用于解决配对必需错误、隧道冲突、远程端点错误以及 SSH 目标配置错误等问题。

下载

• 运行 npm -v 和 which npm，对比输出是否和 node 在同一目录下（例如都位于 /usr/local/bin/）
• 如果 which npm 返回空或路径异常，尝试重装 npm：curl -q https://www.npmjs.com/install.sh | sh（慎用），更稳妥的是用 nvm 管理：nvm install --lts && nvm use --lts
• 检查 npm config get prefix，若指向用户目录（如 ~/npm-global），需确保该路径已加入 PATH，否则全局安装的 CLI 工具（如 nodemon）无法直接调用
• VSCode 终端重启后仍不识别新装的 npm 全局命令？关掉所有终端窗口，再从“终端 → 新建终端”打开，避免复用旧 shell 进程

想一键运行当前 JS 文件，不用每次敲 node app.js

VSCode 不提供默认快捷键执行当前文件，但可通过配置 tasks.json 或利用内置变量实现免输路径。

• 最简方案：在 .vscode/tasks.json 中定义一个 task，"command": "node", "args": ["${file}"]，然后绑定快捷键（如 Ctrl+Shift+B）
• 更轻量做法：在 launch.json 的 configuration 中把 "program" 设为 "${file}"，这样按 F5 就调试当前打开的 JS 文件，无需改配置
• 注意 ${file} 只对单文件有效；如果是多入口项目（如 src/index.js），必须用 "${workspaceFolder}/src/index.js" 显式指定
• 别依赖 Code Runner 插件的“运行代码”按钮——它默认用 node 执行，但不走调试器，断点无效，且对 ES 模块、type: "module" 支持不稳定

调试时提示 Cannot connect to runtime process 或端口被占

这是 Node.js 调试器启动失败的典型报错，本质是 VSCode 无法 attach 到目标进程，常见于端口冲突或启动方式不匹配。

• 确认 launch.json 中 "request": "launch" 对应的是本地启动，而非 "attach"；后者需要程序已运行且暴露调试端口（如 node --inspect-brk app.js）
• 默认调试端口是 9229，若被其他进程占用，可在配置中加 "port": 9230 并确保该端口空闲（lsof -i :9230 或 netstat -ano | findstr :9230）
• 使用 nodemon 类工具热重载时，不能直接在 launch.json 里设 "program": "nodemon" —— VSCode 的 Node 调试器只认 node 进程；正确做法是用 "runtimeExecutable": "nodemon" 并配 "runtimeArgs"
• 如果你在 Docker 或 WSL 里开发，localhost 指向可能不一致，需改用 "address": "0.0.0.0" 并确认防火墙/网络策略放行

真正卡住人的地方，往往不是“怎么配”，而是终端环境没继承、调试端口静默冲突、或者误把 attach 当 launch 用——这些错误不会报具体路径或端口，只甩一句连接失败。