先确认系统终端中 node -v 和 npm -v 能正常执行，再检查 PATH（Windows）或使用 nvm（macOS/Linux），接着切换 npm 镜像源为 https://registry.npmmirror.com，确保 jsconfig.json/tsconfig.json 正确配置，并在依赖更新后重启 VSCode。
node -v 报错时别急着配依赖
VSCode 里装再多插件、写再全的 package.json，只要 node -v 在系统终端里报 command not found，所有依赖管理都跑不起来——这不是配置问题，是环境没到位。
- 先在系统终端（不是 VSCode 集成终端）运行
node -v和npm -v，确认 Node.js 真的装好了 - Windows 用户检查安装时是否勾选了 Add to PATH；macOS/Linux 强烈建议用
nvm管理版本，避免权限和路径冲突 - 即使终端能跑，VSCode 有时会继承错误 shell 环境，可尝试关闭重开集成终端，或在设置里显式填入
node.runtimePath（值为which node输出的绝对路径）
npm install 卡住或超时？先换镜像再执行
国内直连 npm 官源常因网络波动导致安装失败或极慢，这不是项目问题，是网络策略限制。
- 执行
npm config set registry https://registry.npmmirror.com切换到 CNPM 镜像 - 验证是否生效：
npm config get registry应输出https://registry.npmmirror.com - 如果已有
package.json，直接运行npm install；若无，先npm init -y生成基础文件再装依赖 - 避免使用
cnpm：它会生成独立的node_modules结构，与 VSCode 的 IntelliSense 和调试器不兼容
依赖装完但 import 报红？检查三处关键配置
VSCode 里 import 的包名底下持续波浪线，不是插件没装，而是类型定义或路径解析没对上。
Zenlink - Node SDK for ZenHeart
下载
ZenHeart zenlink 与 zenlink-mcp 为 OpenClaw，涵盖安装、MCP 注册、钩子接线、入站轮询及升级维护。
- 确认已执行完整命令
npm install（不是npm i缩写，某些旧版 npm 对缩写支持不稳定） - 检查项目根目录是否存在
jsconfig.json或tsconfig.json，并确保启用了"typeRoots"或"types"字段（尤其用了@types/xxx时） - ESM 项目若混用
require()加载 CommonJS 包，可能触发类型不匹配，优先改用import，或在package.json中加"type": "module"
依赖更新后调试失效？重启 VSCode 才真正生效
修改 node_modules 后，VSCode 不会自动重载类型定义和路径索引——你看到的“未找到模块”提示，大概率是旧缓存还在。
立即学习“前端免费学习笔记（深入）”；
- 执行
npm update或npm install xxx后，务必重启 VSCode（不只是 Reload Window），否则 IntelliSense 和调试器仍按旧快照工作 - 如果用了
npm-check交互式更新，更新完立刻关掉所有打开的 JS/TS 文件，再重新打开，避免编辑器持旧引用 - 大型项目中，
node_modules/.vscode目录偶尔会残留错误缓存，可手动删掉（不影响依赖本身）
最常被跳过的其实是：确认环境变量、镜像源、配置文件存在性这三件事。一旦漏掉任一环，后续所有操作都在无效路径上打转。
