Desktop 如何使用你的 Node 环境

HagiCode Desktop 使用你在系统中自行安装的外部 node 与 npm。请在首次启动 Desktop 前安装 Node.js，并确保这两个命令都能通过系统 PATH 找到。

这篇 FAQ 说明 Desktop 如何找到外部 Node 环境、Agent CLI 的安装位置，以及找不到 Node 或 npm 时的排查方法。

版本要求

需要 Node.js 24 或更高版本（最低要求也是 24）。npm 随 Node.js 一起安装。安装方法见 安装 Node.js。

Git 同样需要自行安装，见 安装指南。

Desktop 如何找到 node 和 npm

Desktop 在启动时读取系统 PATH，并在其中查找 node、npm 与 git。这意味着：

• 您在终端里 node --version 看到的版本，通常就是 Desktop 使用的版本。
• Desktop 只使用您的 Node 环境，不会替换或修改它。
• 如果在 Desktop 已经打开时才安装或升级 Node.js，请完全退出并重新启动 Desktop，让它读取新的 PATH。

版本管理工具与 PATH

在 macOS 和 Linux 上，nvm、fnm 等版本管理工具通常只在 shell 配置文件里设置 PATH。从 Dock、应用菜单或桌面图标启动的 Desktop 不会读取这些配置，可能找不到 node。请从已经能运行 node 的终端里启动 Desktop，或改用系统级安装。

Agent CLI 等托管包安装到哪里

Desktop 的依赖管理页面会发现 PATH 中的 node 与 npm，显示解析出的 npm 全局前缀，并把目录里列出的 CLI 包安装到这个外部全局目录中。

对每个托管的 CLI，Desktop 按以下顺序查找可执行文件：

1. 已存在的托管路径
2. npm 全局 bin 目录（Windows 上包含 .cmd 与 .ps1 启动脚本）
3. PATH

npm 镜像设置会作用于安装与同步操作。卸载同样针对外部的全局目录，并且需要在界面中确认。您可以用下面的命令查看当前的全局目录：

npm prefix -g

如果全局目录位于需要管理员权限的位置，安装时可能出现权限错误，请参考 配置 npm 全局目录。

提示找不到 Node 或 npm 怎么办

1. 在终端运行 node --version，确认 Node.js 版本不低于 24；再运行 npm --version，确认 npm 可用。
2. 如果没有安装或版本过低，请先在 Desktop 之外安装 Node.js。
3. 完全退出并重新启动 Desktop，再回到依赖页面点击刷新。

Desktop 提示需要手动安装某个 CLI 包时，请在 Desktop 之外的终端执行它给出的命令，完成后回到 Desktop 刷新一次，让它重新检测。