常見問題與疑難排解

以症狀為出發點的解答。每個匯入錯誤在 Console 報告中，都會附帶自己的在哪裡／是什麼／為什麼／怎麼修句子——請先從那裡開始查看。

設定與第一次執行

「我在沒有 Addressables 的情況下匯入了此素材——它能編譯嗎？為什麼匯入被鎖定？」

此素材即使沒有 Addressables 也能編譯：使用 Addressables 的程式碼，都位於一個 SHEETFORGE_ADDRESSABLES 版本定義之後。位址載入與 AssetRef@Group 型別確實需要 com.unity.addressables，因此整條管線（匯入．匯出．推送．寫回）會鎖定，直到你安裝它為止。每個進入點都會顯示安裝提示並停止——不會部分執行。

請透過 Package Manager 安裝 com.unity.addressables。入門視窗的 Addressables 列附有一個開啟 Package Manager按鈕，而且這個視窗能正常執行，不會被 Safe Mode 擋住，因為 Editor 即使沒有該套件也能編譯。

如果安裝完成後仍有編譯錯誤殘留，那是來自專案中的其他程式碼——SheetForge 無論有沒有該套件都能編譯。

「我更新到新版本後，專案現在無法編譯。」

匯入 .unitypackage 只會新增與更新檔案，絕不會刪除檔案，因此本產品在較新版本中已淘汰的檔案可能會殘留下來，繼續參照一個已不存在的 API。

編輯器載入時，不具相依性的 SheetForge.Setup 啟動組件會偵測這些已知的淘汰路徑，並主動提議刪除——會先列出每一條路徑，之後才會有任何動作。核准對話框後，編譯即可恢復正常。因為它位於自己獨立的組件中，即使主要組件正在編譯失敗，它依然能持續運作。若想完全略過這個提示，可以在匯入新套件之前，先刪除 Assets/SheetForge 資料夾。

但它無法涵蓋的是你自己撰寫、針對某個已淘汰合約的程式碼——請使用原始碼儲存庫中（發行套件並不隨附）CHANGELOG.md 的升級注意事項表格手動移植。快速上手摘要說明了其內容。

「建立試算表只顯示內建範本——技能示範範本在哪裡？／我該如何新增自己的範本？」

內建的建立試算表清單出貨兩個範本——*物品範例（僅核心類型）*與 Enum definitions（會排出一份 @enum 試算表）——外加「從零開始」。

需要外掛的領域範本（例如技能示範）由該外掛自行註冊，因此只有在外掛存在時才會出現。匯入外掛示範套件後，其技能示範範本就會出現。若要出貨你自己的範本，請實作 ISheetForgeTemplatePlugin——請參閱外掛開發 §4.6。

「我該從哪裡開始？／每次開啟 Editor 都會跳出一個視窗。」

那是入門視窗。它會在 Editor 第一次載入時自動開啟，是建議的進入點——Addressables 狀態、選擇使用中的設定資源、匯入範例，以及執行你的第一次匯入，全都集中在同一個地方。

你可以透過視窗底部的**「編輯器啟動時顯示此視窗」**切換開關關閉自動開啟，並隨時從 Tools ▸ SheetForge ▸ 入門 重新開啟它。

「我匯入了示範套件，但什麼都沒發生——沒有設定資源，也沒有 Addressables 群組。」

每個示範套件都內含一個預先設定好的設定資源，匯入套件時會自動啟用它——但僅限於你尚未擁有自己使用中設定的情況。若你已經有了，則會改為開啟入門視窗，建議你切換，而不會靜默變更你的設定。

接著在 Tools ▸ SheetForge ▸ Data Studio 中按一次 ↓ Pull from source：這會自動建立 Addressables 群組與逐分頁的位址。流程：匯入套件 →（設定資源自動啟用）→ 執行匯入 → Play。

「示範場景只顯示一則文字訊息，而不是示範內容。」

示範是依 Addressables 位址載入的，而這些位址只有在你的機器上執行過一次匯入之後才會存在（群組資源是未提交、可自我修復的快取）。匯入示範套件（其設定資源會自動啟用）並執行一次執行匯入——請參閱快速上手 §5。

（示範已提交的型別使用預設的 SheetForge.Generated 命名空間，因此完全不需要 generatedNamespace 設定——重新匯入會原地重新產生它們。）

「外掛示範的第一次匯入失敗，顯示 `UnknownAssetGroup 'Scripts'`。」

外掛示範有一個型別為 List<AssetRef@Scripts> 的 script 欄，需要一個名為 Scripts 的 Addressables 群組。Addressables 群組是依機器而異的（不會被提交），因此剛匯入的示範尚未擁有它。

示範會在匯入時自動設定該群組（PluginDemoAddressableSetup，會在網域重新載入時，以及你開啟示範場景時觸發），因此正常匯入就能直接運作。如果你仍然看到這個錯誤，請重新開啟示範場景（Tools ▸ SheetForge ▸ Open Plugin Demo Scene）以觸發此設定，然後重新匯入。

這僅適用於外掛示範——你自己的 AssetRef@… 群組，則是由你自行註冊的。

「如果我有多個設定資源，會使用哪一個？」

使用中的那一個。選單、Data Studio 與匯入作業全都會使用使用中的設定資源。可在入門視窗或 Data Studio 工具列的下拉選單（僅在存在多個時顯示）中選擇它。

只有單一設定資源時，第一次匯入會自動選定它。此選擇會依專案與使用者各別儲存（一個 EditorPrefs 指標——不會造成 VCS 異動），若使用中的資源被刪除，也會自動修復。

「我已經有一個試算表資料夾了——最快能讓 SheetForge 指向它的方式是什麼？」

開啟 Data Studio，然後把該資料夾（或單一 .tsv／.csv／.xlsx 檔案）拖放到它上面。

它會主動提議建立一個讀取該資料夾的匯入設定資源，並將其設為使用中，完全不需要手動輸入欄位。如果你已經有使用中設定，對話框會說明此情況，並提供切換的選項。

「我該如何檢查我的專案設定是否正確／為什麼匯入無法執行？」

在 Data Studio 工具列中選擇 ⋯ ▸ 健康檢查。它會回報 ✓／✗ 與建議的修正方式，內容涵蓋：

使用中設定；
來源可存取性——本機資料夾是否存在，或 Google id ＋服務帳戶金鑰路徑，不涉及任何網路呼叫；
匯入 baseline；
產生的程式碼／烘焙／Addressables 是否為最新。

結果會顯示於 Console，並附上一個摘要對話框。

「選單與 UI 開啟時使用了我沒有選擇的語言。」

專案第一次開啟時，SheetForge 會依你 Editor 的系統語言設定其 UI 語言（九種語言可直接對應，其餘則為英文）。它絕不會覆寫你自己設定過的語言。你可以隨時在 Preferences ▸ SheetForge 中變更——請參閱在地化。

（變更語言會觸發一次簡短的重新編譯，因為選單標籤會被重新產生。）

「我複製了儲存庫，結果場景中對烘焙後 SO 的參照都變成 Missing。」

這是預期中的行為：烘焙後的 SO 是依機器而異的快取，具有依機器而異的 GUID。絕對不要讓場景直接參照它們——請依位址載入（SheetForgeDatabases.LoadAsync("Tab")）。執行一次匯入，即可重新建構你本機的快取。

「我的建置被一則 SheetForge 訊息中止了。」

這是建置前新鮮度掛勾在保護你，避免發布一個空的／過時的快取。請照著提示句的說明去做——在 Tools ▸ SheetForge ▸ Data Studio 中按下 ↓ Pull from source——然後再次建置。

匯入與驗證

「匯入執行了，發現了錯誤，結果完全沒有產生任何輸出。」

這是設計使然：只要有一個錯誤 ⇒ 就不會有輸出（不會有部分組裝的結果）。報告會列出每一個問題，附上座標與建議的修正方式——一次修正完畢後重新匯入即可。你絕不會因此而遺失任何工作成果；試算表本身不受影響。

「我可以直接跳到錯誤所在的儲存格嗎？」

可以。人類可讀的 Console 報告中，每個錯誤都附有一個可點擊的**「在 Data Studio 中開啟」**連結；點擊它會開啟 Data Studio、切換至對應分頁，並醒目標示該儲存格（檔案／分頁層級的錯誤則只會聚焦到分頁）。供機器讀取的座標行維持不變，因此 CI／記錄檔擷取不受影響。

「匯入寫入了程式碼、重新編譯了……它完成了嗎？」

完成了。當結構描述是新的／有變動時，匯入在內部會分成兩個階段（程式碼產生 → 編譯／重新載入 → 烘焙），而烘焙會在重新載入之後自動接續完成。請留意 Console 中的最終報告。

如果你的遊戲程式碼因此無法編譯（例如欄重新命名之後），流程鏈會安全中止並提供可據以行動的說明；修正你的程式碼後再次匯入即可。

「出現空白儲存格錯誤，但我原本希望這個儲存格是選填的。」

沒有標記的型別即為必填（靜默污染防護機制）。若要讓儲存格變成選填，你可以：

宣告 float?——型別預設值；
宣告 int=1——明確的預設值；
或使用 List<T>，此時空白儲存格即為空清單。

請參閱試算表語法。

「`1.5` 可以正常匯入，但 `1,5` 會出現錯誤。」

這是刻意的設計：數字不受地區設定影響——小數點永遠使用 .。以逗號表示的小數、NaN，以及 Infinity 都會在入口處被阻擋。

「匯入突然變得非常慢。」

匯入時間與你的資料規模成線性關係（50k 列 × 20 欄，在編輯器中約為 628 ms），即使大量參照同時失效，也依然維持線性——最接近候選建議的搜尋針對每個欄位設有預算，並採用長度預篩選（4,000 筆失效參照時，無頭模式下約為 45 ms）。

如果匯入時間突然比這長得多，該檢視的是試算表的規模，而不是錯誤數量。

「出現未知標記／未知型別錯誤，並附有『你是不是想輸入』的提示。」

@marker 名稱、型別名稱，或 enum 成員的拼字錯誤，都會是錯誤，並附上最接近的候選建議——套用該建議即可。未註冊的型別名稱帶有 @ 同樣也是錯誤（這是針對 RecordId@Tab 這類參照的拼字安全機制）。

Google 試算表

「Google 匯入失敗，顯示 `PERMISSION_DENIED`（403）。」

試算表尚未分享給服務帳戶的 client_email 地址——光有金鑰並不會授予任何權限。開啟 JSON 金鑰，複製 client_email，並將試算表分享給它（匯入需要 Viewer，推送則需要 Editor）。完整流程請參閱Google 試算表設定。

「推送提示需要 SheetsApi。」

你目前處於唯讀（不需驗證）的 ExportUrl 模式。任何寫回操作都需要具備服務帳戶金鑰的 SheetsApi 模式。請參閱來源、匯出與推送。建立服務帳戶與金鑰的完整說明，請參閱Google 試算表設定。

「ExportUrl 匯入失敗，要求提供 gid 對照表。」

這是必要條件：沒有 gid 的匯出網址會靜默地只回傳第一個分頁，因此強制要求提供對照表（分頁名稱 → #gid=）。或者也可以改用不需要對照表的 SheetsApi 模式。

「推送回報有儲存格被略過。」

傳送前重新擷取正式內容時發現了衝突（隊友編輯過某個儲存格、某列移動了位置／消失了、出現重複的鍵值）。被略過的儲存格是一種保護機制，而不是失敗——報告會顯示已套用／已略過的數量。重新匯入以進行調解，然後再次推送。

「我在本機刪除了列，但推送之後它們仍留在 Google 試算表中。」

列的刪除絕不會被推送（對正式試算表進行位置式刪除並不安全）——你只會得到一則通知。請直接在試算表中刪除這些列，然後重新匯入。

編寫

「Ctrl+Z 沒有復原我暫存的變更。」

有兩個邊界情況：

取得焦點的文字欄位會優先攔截 Ctrl+Z——請先點擊別處，再執行復原；
在「反映至試算表」成功之後，暫存歷史記錄會被清除，因此復原只在反映之前的工作階段內有效。

反映之後，請直接編輯試算表（因為它才是權威來源）。

來源為 xlsx 的分頁不能被重新命名（活頁簿保護機制）；
會涉及 xlsx 分頁的鍵值重新命名傳播，會封鎖整個批次（不允許部分反映）。

請直接編輯該活頁簿，然後重新匯入。

沒有快取數值的公式儲存格；
錯誤儲存格；
儲存格內的定位字元／換行字元。

請將公式實體化為數值；使用 ; 來表示清單。