Desktop Node 執行環境

HagiCode Desktop 內建一套由 Desktop 管理的 Node 工具鏈。它不會接管你電腦上的全域 Node 安裝。它的目的，是為 Desktop 啟動流程與執行期相關流程提供穩定且可驗證的執行時基礎。

如果你在診斷資訊中看到 portable-fixed/toolchain、想知道 Desktop 正在使用哪個 node，或不理解為什麼你系統中的 Node 版本不會直接決定 Desktop 的執行時行為，就應該閱讀這篇 FAQ。

Desktop 為什麼要內建 Node

Desktop 需要在不同作業系統、安裝通路與使用者環境中執行相同的支援流程。如果它只依賴使用者現有的 Node 安裝，技術支援就必須同時處理過時版本、缺少 npm、PATH 順序錯誤、全域套件污染，以及組織內部特定的 registry 政策等問題。

Desktop 更具體地將這件事描述為：為受管理的 CLI 提供隔離的 Node/npm 執行時，而不是重用系統層級的環境。這種設計主要有以下好處：

• 版本一致：Desktop 使用固定的 Node 22 執行時契約，而不是猜測使用者本機安裝的是哪個主版本。
• 啟動流程可控：由 Desktop 管理的命令可以優先使用隨附封裝的 node 與 npm。
• 設定邊界清楚：與 CLI 相關的設定會和主機層級的全域設定分離，讓更新、切換與修復流程不容易被系統環境差異打斷。
• 降低衝突：內建路徑只會套用到 Desktop 建立的命令執行環境，不會取代你在終端機中的全域 Node。
• 對主機行為侵入性低：這種隔離方式避免把工具鏈狀態寫進使用者現有的 Node/npm 環境，而移除 Desktop 也不會干擾機器上原本已存在的 Node、npm 或相關設定。

Desktop 如何選擇 Node 路徑

當你正常執行 Desktop 時，Desktop 會優先使用隨應用程式安裝的 Node 工具鏈，而不是先讀取你系統中的 Node 安裝。這樣可以讓你在終端機裡使用的 Node 版本，和 Desktop 執行時預期的 Node 版本彼此分離。

當內建工具鏈啟用時，Desktop 建立的命令執行環境會把內建工具鏈路徑放在 PATH 的最前面。因此，即使你的系統還安裝了其他版本的 Node，Desktop 管理的流程仍會優先解析到 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 命令不可變的來源。受管理的全域套件則會安裝在 Electron 的使用者資料目錄下：

userData/node22/npmGlobal

如果 Desktop 之後升級到 Node 24，它會改用獨立的套件樹，例如 userData/node24/npmGlobal。原本為 Node 22 安裝的套件仍會留在磁碟上，但在重新安裝到新的主版本前綴之前，不會被視為已安裝到 Node 24。

Desktop 的依賴狀態只會檢查目前啟用的 userData/node<major>/npmGlobal 前綴。位於此前綴之外的套件檔案，不會納入依賴管理。