文章目錄
在 Unity CLI 出現以前，我們得人工處理 Unity Hub 的編輯器安裝、模組等工作。於 CLI 功能推出後，現在可以直接讓 AI Agent 透過 CLI 來自動化安裝編輯器與所需的模組，甚至能搭配服務帳戶來執行 CI 自動化測試。
Unity CLI 目前為實驗版，指令與參數於後續更新可能會有變動，請以 Unity CLI 官方文件 為準。
本文指令於 2026 年 9 月 1 日依官方文件與 Unity CLI command reference 重新核對。Windows 請使用 PowerShell，macOS／Linux 使用 Bash；安裝前要先確認磁碟空間、Unity 帳號與授權類型，CI 才另外準備服務帳戶。由於 CLI 仍在 beta，實際旗標以目前安裝版本的 unity <command> --help 為準。
指令速查
常用指令：
| 指令 | 說明 |
|---|---|
unity --help |
查看指令說明 |
unity open ./MyProject |
開啟 Unity 專案 |
unity editors -i |
列出已安裝編輯器 |
unity install 2021.3.45f2 |
安裝編輯器 |
unity install 2021.3.45f2 -m android --cm |
安裝編輯器與模組 |
unity install-modules -e 2021.3.45f2 -m android --cm |
追加安裝模組 (已安裝編輯器) |
unity auth status |
查看登入狀態 |
unity auth login |
登入 |
unity auth logout |
登出 |
unity license status |
查看授權狀態 |
unity license activate --personal --accept-eula |
啟用免費個人授權 |
unity license return -y |
退回授權 |
unity upgrade |
升級 Unity CLI |
安裝 Unity CLI
根據平台輸入指令安裝 Unity CLI：
Windows：
1$env:UNITY_CLI_CHANNEL='beta'; irm https://public-cdn.cloud.unity3d.com/hub/prod/cli/install.ps1 | iex
macOS 或 Linux：
1curl -fsSL https://public-cdn.cloud.unity3d.com/hub/prod/cli/install.sh | UNITY_CLI_CHANNEL=beta bash
安裝 Unity 編輯器與模組
假設我還沒安裝編輯器，要安裝 2021.3.45f2 版本編輯器和 Android、Windows IL2CPP、WebGL 模組，請輸入以下指令 (–cm 是指自動安裝所以依賴的模組，環境會最完整)：
1unity install 2021.3.45f2 -m android windows-il2cpp webgl --cm
如果已經安裝好此版本編輯器，則輸入以下指令用追加的方式來安裝模組：
1unity install-modules -e 2021.3.45f2 -m android windows-il2cpp webgl --cm
編輯器版本限制
Unity CLI 可以讓你安裝任意版本的編輯器，但部分版本只限定企業版授權才能用，免費個人授權會打不開。所以於決定要安裝的版本之前，請先到 Unity Download Archive 查詢版本資訊。如果有標註綠色的 Enterprise and Industry only 就代表免費授權是不能啟動的，目前 2021 版能安裝的最新版本是 2021.3.45f2。
從 WSL2 呼叫 Windows 的 Unity CLI
如果你和我一樣使用 Codex，於 Windows 上通常會讓他跑在 WSL2 中。當已經在 Windows 上安裝好 Unity CLI 時，其實就可以直接調用，差異在於不是用 unity 而是 unity.exe。
1unity.exe --version
2unity.exe editors -i
讓 AI Agent 使用 Unity CLI
如果想讓 AI Agent 在操作 Unity 編輯器時自動使用 CLI，可以在專案的 AGENTS.md 補上以下規則：
1- 進行 Unity 編輯器、專案相關操作時，優先使用 Unity CLI，先執行 `unity.exe --help` 讀取指令說明。
確認安裝結果
安裝 CLI 後先執行 unity --version；Windows 上從 WSL2 呼叫時則執行 unity.exe --version。接著用 unity auth status 確認登入狀態，再用 unity editors -i 核對剛才安裝的編輯器版本。安裝 Android 等模組後，可執行 unity install-modules -e 版本 -l 查看該版本可用模組，並實際開啟目標專案確認 Editor 能正常啟動。
常見失敗與移除
終端機找不到 unity 時，先重新開啟終端機並檢查安裝目錄是否在 PATH。install-modules 找不到編輯器時，要確認該 Editor 是由 Unity Hub 或 Unity CLI 安裝；官方文件說明，手動放入的 Editor 不能直接用這個指令追加模組。版本能安裝卻無法啟動時，再回到 Download Archive 核對授權限制，不要重複下載同一版本。
安裝錯版本時，可先執行 unity editors -i 確認精確版本，再使用 unity uninstall 版本 移除。CI 或共用機器不再使用授權時，應依實際授權類型執行 unity license return 釋放席次；這兩個動作都會改變本機狀態，執行前要再次確認目標版本與授權。
總結
Unity CLI 最適合處理可重複的 Editor、模組與專案操作。給 Agent 使用時，先要求它讀目前版本的 --help，完成後再以 auth status、editors -i 與實際開啟專案驗證，不能只把指令成功結束當成安裝完成。
