ASDF切换Node后VSCode终端仍用旧版本，根本原因是~/.asdf/shims未加入PATH或shell配置未加载；需在~/.zshrc末尾添加export PATH="$HOME/.asdf/shims:$PATH"并source生效，同时确保.tool-versions置于项目根目录且格式正确（如nodejs 20.15.0），调试器则须在launch.json中硬编码"runtimeExecutable": "/Users/xxx/.asdf/shims/node"。
ASDF切换Node后VSCode终端仍用旧版本？先确认shims是否生效
根本不是ASDF没切成功，而是~/.asdf/shims没进PATH，或者当前终端压根没加载shell配置。VSCode终端启动时只读一次PATH快照，改完~/.zshrc不source或不新开终端，它就永远看不到新路径。
实操建议：
- 在VSCode集成终端里运行
echo $PATH，确认输出开头有/Users/xxx/.asdf/shims（macOS）或/home/xxx/.asdf/shims（Linux） - 没有？立刻在
~/.zshrc（或~/.bashrc）末尾加：export PATH="$HOME/.asdf/shims:$PATH" - 加完必须执行
source ~/.zshrc，否则当前终端不会更新——关掉所有终端标签页再点「+」新建一个才管用 - 验证：
which node应输出~/.asdf/shims/node，不是/usr/local/bin/node或~/.nvm/versions/...
项目级Node版本不生效？检查.tool-versions位置和格式
.tool-versions文件放错地方、格式多一个空格，ASDF就当它不存在。它只从当前工作目录往上逐层找，直到根目录，一旦找到就停，不会合并多个文件。
实操建议：
-
.tool-versions必须放在项目根目录，也就是package.json或node_modules所在目录，不能在src/或backend/子目录里 - 内容严格为单行：
nodejs 20.15.0，不能写成nodejs 20.15.0 # comment，也不能有前后空格 - 运行
asdf current nodejs，输出应为20.15.0（不是unset或system） - 如果输出
unset，说明ASDF根本没读到文件——检查.gitignore是否误删了.tool-versions，这个文件必须提交到仓库
VSCode调试器还是跑错Node版本？runtimeExecutable不能依赖${env:NVM_BIN}
ASDF不用NVM_BIN，它靠shims代理，所以launch.json里写"runtimeExecutable": "${env:NVM_BIN}/node"会直接展开为空，调试器启动失败。你得告诉它明确用哪个shim。
Zenlink - Node SDK for ZenHeart
下载
ZenHeart zenlink 与 zenlink-mcp 为 OpenClaw，涵盖安装、MCP 注册、钩子接线、入站轮询及升级维护。
实操建议：
- 不要用环境变量间接引用，直接硬编码shim路径：
"runtimeExecutable": "/Users/xxx/.asdf/shims/node" - 路径必须绝对，不能用
~或$HOME——VSCode调试器不解析这些 - 确保该路径真实存在且可执行：
ls -l ~/.asdf/shims/node应显示软链接指向~/.asdf/installs/nodejs/20.15.0/bin/node - 如果项目跨平台协作，Windows用户需改用
C:/Users/xxx/.asdf/shims/node.exe，注意反斜杠要双写或全用正斜杠
多个项目同时打开，Node版本互相污染？关掉自动继承环境变量
VSCode默认让所有终端共享同一套环境变量快照，A项目切了Node 20，B项目终端里node -v也变成20——这不是ASDF的问题，是VSCode把PATH全局缓存了。
实操建议：
- 在
settings.json里关掉terminal.integrated.inheritEnv，设为false - 每个项目单独配
.vscode/settings.json，写死"terminal.integrated.env.osx": {"PATH": "/Users/xxx/.asdf/shims:/usr/bin:/bin"} - 这样不同窗口的终端各自加载自己的
PATH，互不干扰 - 注意：改完要关掉所有终端标签页，再新建——重开VSCode都不管用
ASDF本身不维护状态，它只响应.tool-versions和PATH顺序。VSCode终端是否“看到”正确版本，完全取决于你有没有把shims塞进PATH最前面，以及那个.tool-versions文件是不是真躺在项目根目录、格式有没有多一个空格。任何一步出错，都会导致环境变量漂移——而且漂得无声无息，node -v看着对，实际运行时却报Cannot find module 'node:fs'。
