Desktop Node 环境说明

HagiCode Desktop 会随应用一起提供一套由 Desktop 管理的 Node 工具链。它的目标不是接管你电脑上的全局 Node 环境，而是让 Desktop 自己启动和运行相关流程时拥有稳定、可验证的运行基础。

这篇 FAQ 适合想了解以下问题时阅读：为什么诊断里出现了 portable-fixed/toolchain 路径、Desktop 到底用了哪个 node，以及为什么系统 Node 版本不会直接决定 Desktop 的运行行为。

为什么 Desktop 要内置 Node

Desktop 需要在不同操作系统、不同安装来源和不同用户环境里启动相同的一组辅助流程。如果完全依赖用户已经安装的 Node，支持团队会同时面对版本过旧、npm 缺失、路径顺序错误、全局包污染、公司镜像源策略等问题。

Desktop 里还有一个更具体的说法：它使用独立的 Node/npm 运行时来承载托管 CLI，而不是直接复用系统环境。这样做主要有这些原因：

• 版本一致：Desktop 使用固定的 Node 22 运行时契约，不需要猜测用户机器上的 Node 主版本。
• 启动流程可控：Desktop 管理的命令可以优先使用随应用打包的 node 和 npm。
• 配置边界清晰：CLI 依赖的配置会与主机范围的全局配置区分开，升级、切换和恢复时不容易被系统环境差异打断。
• 降低冲突：内置路径只作用在 Desktop 创建的命令环境中，不会替换用户终端里的全局 Node。
• 不污染宿主机：这种隔离方式可以避免 HagiCode 把工具链状态写进用户原本的 Node/npm 环境；卸载 Desktop 时，也不会影响你系统里已经存在的 Node、npm 和配置。

Desktop 如何选择 Node 路径

用户正常运行 Desktop 时，Desktop 会优先使用随应用一起安装的 Node 工具链，而不是优先读取系统里已经安装的 Node。这样可以避免“用户终端里的 Node 版本”和“Desktop 运行所需 Node 版本”互相影响。

当内置工具链处于启用状态时，Desktop 创建的命令环境会把内置工具链相关路径放到 PATH 前面。因此，即使你的系统已经安装了另一个版本的 Node，Desktop 管理的流程也会优先解析到它自带的 Node 和 npm。

这只影响 Desktop 自己创建的运行环境。你在系统终端中直接执行 node、npm 或其他命令时，仍然使用你原本的系统环境和 shell 配置。

在诊断信息或 Desktop 启动的子进程环境中，你可能会看到类似下面的变量：

HAGICODE_PORTABLE_TOOLCHAIN_ROOT=/path/to/portable-fixed/toolchain

这个变量表示当前 Desktop 管理的运行环境已经识别到内置工具链根目录。看到这类路径并不表示 Desktop 修改了你的系统 Node；它只说明 Desktop 在自己的运行范围内使用了随应用提供的 Node 环境。

Desktop 把托管 npm 包安装到哪里

Desktop 会把运行时文件和可变的 npm 包文件放在不同位置。类似 portable-fixed/toolchain/node 的内置工具链路径只作为 Desktop 托管的 node 和 npm 命令来源，不再作为全局 npm 包安装目录。托管的全局包会安装到 Electron 的用户数据目录：

userData/node22/npmGlobal

如果 Desktop 后续切换到 Node 24，会使用独立的 userData/node24/npmGlobal 包目录。Node 22 下已经安装的包会保留在磁盘上，但不会被 Node 24 视为已安装，需要重新安装到新的主版本目录中。

Desktop 的依赖项状态只检查当前生效的 userData/node<major>/npmGlobal 前缀。这个前缀之外的包文件不会参与依赖项管理判断。