# 疑難排解 — AI Game Dev 應用程式與 CLI · AI Game Developer Wiki

解決 AI Game Dev 應用程式與 gamedev CLI 的常見問題：登入、模型、引擎外掛與編輯器連線、套件、本機與雲端生成。

本頁面由英文機器翻譯而成。[閱讀英文原文](https://ai-game.dev/docs/wiki/app/troubleshooting)。

本頁彙整 AI Game Dev 應用程式與 `gamedev` CLI 使用者最常遇到的問題，並說明可能原因與解決方式。請依領域尋找對應的症狀：登入、模型、引擎連線、套件、本機模型、雲端生成或 CLI。

## 登入

**登入用的瀏覽器視窗沒有開啟。** 沒有設定預設瀏覽器，或防火牆阻擋了登入。請設定預設瀏覽器，然後再次選擇 **Sign in**。若位於公司 Proxy 後方，請允許對 ai-game.dev 的對外 HTTPS 連線。在 CLI 中，`/login` 會顯示一組代碼和一個網址，您可以改用其他裝置開啟。

**應用程式回到登入畫面，或 CLI 要求執行 `/login`。** 您的工作階段已過期或被撤銷，例如從帳戶的 Connected devices 頁面撤銷。請重新登入；您的對話與設定都會保留。

**無介面（headless）執行以代碼 2 結束。** 電腦尚未登入、提示內容為空，或資料夾／旗標不可用。請以互動方式執行一次 `gamedev` 並輸入 `/login`。請參閱[結束代碼](https://ai-game.dev/zh-hant/docs/wiki/app/cli#headless)。

**登入了錯誤的帳號。** 應用程式、CLI 與 `gamedev acp` 在每台電腦上共用同一組登入。請在 CLI 使用 `/login --switch`，或在桌面應用程式中登出後再登入。

更多流程說明：[驗證指南](https://ai-game.dev/docs/auth)。

## 模型

**模型清單顯示為載入中或無法連線。** 清單來自 ai-game.dev。若沒有連線，也沒有上次清單的已存副本，就沒有內容可顯示。請檢查連線後重新開啟選擇器。

**某個模型顯示為灰色。** 原因會顯示在模型名稱下方：可能需要更高的方案（請參閱[定價頁面](https://ai-game.dev/pricing)）、可能未在您帳單地址所在的國家／地區提供（請參閱[模型可用性](https://ai-game.dev/model-availability)），或需要在帳戶中完成年齡確認。模型清單底部會顯示判斷可用性所依據的地區。

**CLI 拒絕 `--model`。** 您的帳戶無法使用該模型。請用 `/model` 選擇其他模型，或傳入其他 id。

**用量很快就用完。** 用量以每月額度的百分比顯示。同樣的工作量下，較大的模型會消耗更多額度；例行編輯請使用較快的模型，並只開啟工作階段真正需要的工具。

## 引擎外掛與編輯器連線

**CLI 表示資料夾中沒有 Unity、Godot 或 Unreal 專案。** 請開啟專案的根資料夾：Unity 是含有 `ProjectSettings/` 的資料夾，Godot 是含有 `project.godot` 的資料夾，Unreal 則是含有 `.uproject` 檔案的資料夾。

**外掛沒有安裝成功。** 找不到引擎或專案。請確認引擎已安裝（Unity Hub、Unreal Engine 或 Godot），且您開啟的是實際的專案資料夾，然後在側邊欄點擊 **Install Package**，或執行 `/install-plugin`。若要手動安裝，請依照 [Unity](https://ai-game.dev/zh-hant/docs/wiki/unity/installation)、[Unreal](https://ai-game.dev/zh-hant/docs/wiki/unreal/installation) 或 [Godot](https://ai-game.dev/zh-hant/docs/wiki/godot/installation) 的指南操作。

**側邊欄出現 Update Package。** 有較新的外掛版本可用。點擊即可更新專案中的外掛。

**編輯器顯示「Disconnected」。** 編輯器尚未完成授權，或失去了 Cloud 連線。請在編輯器中開啟 **AI Game Developer** 視窗，選擇 **Cloud**，點擊 **Authorize**，然後等待出現 **Ready**。

**代理等待編輯器很久。** 大型專案開啟需要一段時間。應用程式最多等待 15 分鐘讓編輯器啟動，再最多等待 2 分鐘讓其工具就緒。按下 **Stop** 可取消等待；已經啟動的編輯器會保持開啟。若事先自行開啟編輯器，長時間的工作階段就不必等待。

**建立專案時顯示未安裝引擎編輯器。** 請先安裝引擎，或在建立對話框中手動選擇已安裝的編輯器。

## 套件

**「需要 AI Game Dev >=X，目前為 Y」。** 該套件需要較新版本的應用程式。請更新應用程式（請參閱[安裝說明](https://ai-game.dev/zh-hant/docs/wiki/app/installation#updates)）。

**某個套件顯示警告數量。** 開啟 Packages 視窗、選取該套件，然後查看其 **Errors** 分頁。應用程式記錄檔中 `pkg:<id>` 底下有詳細資訊。

**專案中的套件停止運作。** 若套件主機在五分鐘內當機三次，就不會自動重新啟動。請在 Packages 視窗點擊 **Reload**，或在 CLI 執行 `/packages reload`。

**某個套件沒有更新。** 自動更新是依套件與電腦分別設定：請檢查其 **Auto-update** 開關。來自本機資料夾的套件，以及固定在特定標籤的 GitHub 來源套件，永遠不會自動更新。請使用 **Check for updates** 或 `gamedev pkg update <id>`。

**某個版本被標示為「not in registry anymore」。** 該版本已被撤回。它仍可繼續運作，但永遠不會被列為更新目標。

**某個套件因相依項目被排除而遭到封鎖。** 該相依項目在此專案的某一層級被關閉。請在 Packages 視窗選擇 **Include it again**，或執行 `gamedev pkg include <id>`。

**「套件 X 的工具在此工作階段無法使用」。** 此工作階段已設定同名的 MCP 伺服器（由您、專案或引擎設定）。請在 **Settings**、**MCP servers** 中重新命名或移除另一個伺服器。

**連結的套件資料夾沒有任何作用。** `id-mismatch` 表示該資料夾的 manifest 指向另一個套件；`not-found` 表示資料夾已移動。請執行 `gamedev pkg unlink <id>` 以回到已發佈的版本。

**聊天中缺少某個工具。** 已安裝的套件不會為每個聊天加入工具。請在工作階段的 Tools 列開啟該工具（CLI：`/config`、**Tools**）。變更會從下一則訊息開始生效。

## 本機影像與影片模型

**我的電腦沒有提供某個模型。** 每個模型都會列出適合的硬體；應用程式只會提供您的 GPU、視訊記憶體與驅動程式能執行的模型。若您更換了硬體或驅動程式，請執行 `/images redetect`。請參閱[硬體需求表](https://ai-game.dev/zh-hant/docs/wiki/app/packages-catalog#local-image-models)。

**生成因「記憶體不足」而失敗，或速度非常慢。** 視訊記憶體不足的執行會以較小的記憶體預算重試一次。若默默退回 CPU 執行，會回報為失敗而非隱藏。請改用較輕量的模型（例如 Lightning 變體或 Z-Image Turbo），或關閉其他大量使用 GPU 的程式。`/images stop` 會取消排隊中的影像並釋放 GPU。

**磁碟已滿。** 請在 **Settings**、**Model storage** 中將模型儲存位置移到較大的磁碟機，或使用 `/images storage <new folder>`；`/images free-space` 會刪除沒有模型使用的檔案。

**影像執行環境被封鎖或已損毀。** 請執行 `/images reinstall` 重新設定。

## 雲端生成

**代理表示尚未開啟雲端生成。** 請在工作階段的 Tools 列開啟 **Cloud generation**，或在 CLI 使用 `/cloud ask`。

**無法使用某個雲端模型。** 雲端生成僅限付費方案，部分模型需要 Studio 或更高方案，部分模型則未在所有地區提供。**Models** 分頁會標示原因。作業失敗不會消耗您的額度。

## SuperCollider 與 Blender

**在 Linux 上音樂不會開始播放。** SuperCollider 執行環境目前僅支援 Windows 與 macOS。

**找不到 Blender。** 執行 `/blender list` 可查看應用程式找到的所有 Blender，執行 `/blender setup` 可重新設定（可選擇附上您的 Blender 路徑），或讓 `/blender` 下載可攜版的 Blender。需要 Blender 4.2 或更新版本。

## CLI 與背景服務

**CLI 版本過舊。** 請執行 `gamedev update`。

**「執行中的主機尚未提供……。請關閉所有 AI Game Dev 視窗與 CLI，然後重新啟動」。** 背景服務的版本比您啟動的 CLI 或應用程式舊。請關閉所有 AI Game Dev 視窗與 CLI 後重新啟動，或在 CLI 使用 `/update now`。

**我需要記錄檔來回報錯誤。** `gamedev daemon status` 會顯示背景服務的狀態，`gamedev daemon logs --lines 200` 會印出最近的記錄。請在 Discord 或 GitHub 分享相關部分，切勿分享您的憑證。

## 還是卡住了

請查看[常見問題](https://ai-game.dev/zh-hant/docs/wiki/app/faq)、網站[常見問題](https://ai-game.dev/docs/faq)與[版本說明](https://ai-game.dev/zh-hant/releases)，瞭解最近的修正。

---

Source (HTML): https://ai-game.dev/zh-hant/docs/wiki/app/troubleshooting

Machine-translated (zh-Hant) from the English page: https://ai-game.dev/docs/wiki/app/troubleshooting