根本原因是VSCode未继承shell环境变量：macOS/Linux因GUI启动不加载~/.zshrc，Windows因安装未勾选“Add to PATH”；需分别通过终端启动code .或手动配置系统PATH，并彻底重启VSCode验证。

node -v 在终端能跑，但 VSCode 里报 command not found

这不是插件或 VSCode 的问题，而是它没继承 shell 的环境变量。macOS/Linux 下从 Dock 或 Spotlight 启动 VSCode，不会自动 source ~/.zshrc 或 ~/.bash_profile；Windows 则常因安装时没勾选 “Add to PATH” 导致系统级 PATH 缺失。

• macOS/Linux：在终端执行 which node，确认路径（如 /opt/homebrew/bin/node）已写入 shell 初始化文件，并运行 source ~/.zshrc；之后必须彻底退出 VSCode，再用终端执行 code . 启动
• Windows：打开“系统属性 → 高级 → 环境变量”，把 C:\Program Files\nodejs\ 加进“系统变量”的 PATH，重启 VSCode
• 验证唯一方式：在 VSCode 内置终端（Ctrl + `）里执行 node -v 和 npm -v，有输出才算过关

launch.json 的 program 字段总指向错误路径

断点灰掉、提示 Cannot launch program，90% 是因为 program 没指向一个真实可执行的 .js 文件——不是源码、不是文件夹、不是相对路径字面量。

Rydberg Agent Node

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

下载

• 正确写法："program": "${workspaceFolder}/src/index.js"（推荐，跨平台安全）
• 错误写法："program": "src/index.js"（缺 ${workspaceFolder}/，VSCode 不会自动补前缀）
• 错误写法："program": "./src/index.js"（. 在这里不解析，等同于字符串字面量）
• TypeScript 项目：别指 src/index.ts；要么配 preLaunchTask 编译到 dist/ 后指 dist/index.js，要么改用 runtimeExecutable: "npx" + runtimeArgs: ["ts-node", "src/index.ts"]

ESM 项目调试时 Cannot use import statement outside a module

Node 默认按 CommonJS 解析，遇到 import 就崩。这不是语法错，是模块类型没对齐。

• 必须在项目根目录的 package.json 中显式声明："type": "module"
• 如果用 code-runner 插件，需手动改其 executorMap：把 javascript 对应值设为 "node --experimental-specifier-resolution=node $fileName"
• VSCode 调试器（pwa-node）也依赖这个 "type" 值；没声明就强行 import，断点可能命中但 require() 会失败，process.cwd() 行为也可能异常

用 nodemon 或 ts-node 调试时断点失效

这类工具接管了启动流程，VSCode 默认的 launch 模式无法稳定注入调试逻辑，强行配置 runtimeExecutable 容易断连或跳过断点。

• nodemon：不要直接让 program 指向它；改用 request: "attach" 模式——先在终端跑 nodemon --inspect-brk src/server.js，再在 launch.json 新增 attach 配置连 port: 9229
• ts-node：优先用 type: "pwa-node"，配 runtimeExecutable: "npx" 和 runtimeArgs: ["ts-node", "src/index.ts"]；避免混用 ts-node 和旧版 node 调试器
• 注意：所有带 --inspect 的命令，端口不能被其他进程占用；lsof -i :9229（macOS/Linux）或 netstat -ano | findstr :9229（Windows）可查冲突

真正卡住人的，从来不是断点怎么打，而是 node 命令在哪、program 指向哪、模块类型是否对齐这三件事没对上——它们发生在 VSCode 启动的一瞬间，无声无息，但决定后续所有调试行为是否成立。