Desktop 如何使用你的 Node 环境

HagiCode Desktop 不再随应用提供 Node.js 或 npm，也不再内置其他 Node 工具链。Desktop 安装包里内置的只有运行 Hagicode Server 所需的 .NET 运行时；凡是需要 Node 的地方，它都使用你系统里已经安装的 node 与 npm。

这篇 FAQ 适合想了解以下问题时阅读：Desktop 到底用了哪个 node、Agent CLI 被装到了哪里、Desktop 提示找不到 Node 时该怎么办，以及从旧版本升级后遗留的 portable-fixed/toolchain 目录是什么。

版本要求

需要 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 按以下顺序查找可执行文件：

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

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

npm prefix -g

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

提示找不到 Node 或 npm 怎么办

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

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

升级后看到的 `portable-fixed/toolchain` 是什么

较早的 Desktop 版本曾经随应用打包一套 Node 工具链，诊断信息里会出现 portable-fixed/toolchain 路径或 HAGICODE_PORTABLE_TOOLCHAIN_ROOT 变量，托管包则安装在用户数据目录下的 node22/npmGlobal 之类的位置。

当前版本已经移除这套内置工具链：