node -v 能跑通才是前提，否则后续所有配置都白搭；VSCode 不自带 Node.js，仅调用系统 PATH 中的 node 命令；必须在系统终端执行 node -v 和 npm -v 验证，报错则需重装 LTS 版并勾选 Add to PATH、路径纯英文无空格，改环境变量后须彻底重启 VSCode。
node -v 能跑通才是前提
没这步，后面所有配置都白搭。VSCode 不自带 Node.js，它只是调用系统 PATH 里的 node 命令。很多人卡在“F5 调试报错”或“import 报语法错误”，其实根本不是 VSCode 设置问题，而是 node 命令在终端里根本跑不起来。
必须在系统终端（不是 VSCode 内置终端）里执行：
node -v npm -v
两个都要输出版本号。如果报 'node' is not recognized as an internal or external command，说明安装时没勾选 Add to PATH，或路径含空格/中文（比如 C:Program Files
odejs 或 D:软件
odejs）。重装 LTS 版，勾选 Add to PATH，路径选纯英文无空格目录（如 C:
odejs）。
改完环境变量后，必须完全关闭并重启 VSCode——它不会自动刷新 PATH。
package.json 里 type 字段决定 import/export 是否生效
Node.js 默认按 CommonJS 解析 .js 文件，import 和 export 会直接报 Cannot use import statement outside a module。这不是插件或设置能绕过的，是运行时行为。
解决方式只有两种，选其一：
- 在项目根目录
package.json中加"type": "module"，之后所有.js文件都按 ES Module 解析 - 把文件改成
.mjs后缀（如index.mjs），不用改package.json
注意：type: module 会影响 require() 行为，且 exports 字段必须显式声明，否则 require('./lib') 可能失败。临时验证语法建议先用 require() + module.exports，稳。
ZenHeart zenlink 与 zenlink-mcp 为 OpenClaw，涵盖安装、MCP 注册、钩子接线、入站轮询及升级维护。
launch.json 配置 runtimeExecutable 防止多版本冲突
如果你用 nvm（macOS/Linux）或 nvm-windows 管理多个 Node.js 版本，VSCode 调试器默认从 PATH 找 node，但可能和你在终端里 node -v 看到的不是同一个。结果就是断点不触发、process.version 对不上、甚至 import 行为不一致。
在项目根目录建 .vscode/launch.json，强制指定路径：
{
"version": "0.2.0",
"configurations": [
{
"type": "node",
"request": "launch",
"name": "Current File",
"program": "${file}",
"runtimeExecutable": "/usr/local/bin/node" // macOS/Linux
// "runtimeExecutable": "C:\nodejs\node.exe" // Windows
}
]
}
验证是否生效：在代码里加 console.log(process.execPath)，对比调试器输出路径和 runtimeExecutable 是否一致。
ESLint + Prettier 协同要禁用冲突规则
ESLint 默认按 CommonJS 规则校验，遇到 import 就报错；Prettier 格式化可能插入分号，而 ES Module 要求严格分号省略。两者不配好，编辑器里红波浪线满天飞，保存还自动改出错。
关键配置项（放在 .eslintrc.js）：
parserOptions: { ecmaVersion: 'latest', sourceType: 'module' }- 装
eslint-config-prettier并在extends末尾加上'prettier'，关掉所有和 Prettier 冲突的规则 -
.prettierrc里加"semi": false，避免分号干扰 ES Module
VSCode 设置里打开 eslint.enable 和 editor.formatOnSave，但别让 Prettier 直接接管 ESLint 的语法检查——那是它的上游职责。
真正麻烦的从来不是语法本身，而是 node 版本、模块系统、工具链三者之间那几处不声不响的对齐点。比如 node -v 输出 v20.11.0，但调试器调的是 v18.17.0；比如 package.json 没写 type，却在代码里混用 import 和 require；再比如 ESLint 配了 ecmaVersion: 2024，但 node 还没原生支持那个特性——这些地方不手动核对，光靠插件自动提示根本兜不住。
