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 重新整理一次，讓它重新偵測。