對遊戲建構、安裝及執行程序進行偵錯

引言

以下指南說明如何使用適用於 Unity 的 Firebase SDK，對 Unity 遊戲的編譯和建構程序進行偵錯。以下說明如何針對新平台設定及建構遊戲，或在更新後，瞭解如何調查及解決許多更常見的問題。系統會按照程序中這些錯誤發生的時間來排列這些錯誤。請依序查詢這些 ID 並解決問題。

除了本文件以外，如需更多資訊，請參閱「Unity 專用 Firebase 常見問題」。

Play 模式編譯問題

嘗試啟動行動版之前，可能會在編輯器內測試時，發生第一類別的建構問題。本節著重在 Play 模式之前和期間發生的所有 Firebase 錯誤。

當 Unity 啟動或偵測到依附元件、程式碼或其他資產的變更時，會嘗試重新建構專案。如果專案當時無法編譯，編輯器會將編譯錯誤記錄到主控台；如果您嘗試進入 Play 模式，您會在 Unity 的「Scene」分頁中收到讀取 All compiler errors have to be fixed before you can enter playmode! 的錯誤彈出式視窗。

對 Firebase 相關的編譯問題進行偵錯

缺少類型、類別、方法和成員

如果編輯器和編譯器無法找到必要的類型、類別、方法和成員，就會發生許多 Firebase 問題。引發這個問題的常見症狀為下列幾種形式：

The type or namespace name ‘<CLASS OR NAMESPACE NAME>' could not be found. Are you missing a using directive or an assembly reference?

The type or namespace name <TYPE OR NAMESPACE NAME> does not exist in the namespace ‘Firebase<.OPTIONAL NESTED NAMESPACE NAME PATH>' (are you missing an assembly reference?)

‘<CLASS NAME>' does not contain a definition for ‘<MEMBER VARIABLE OR METHOD NAME>'

解決方法：

1. 您要在程式碼中使用 Firebase 類別或方法時，請務必為特定 Firebase 產品提供正確的 using 指令，以提供這些類別或方法。

   1. MechaHamster: Level Up With Firebase Edition 範例：
      1. using Firebase.RemoteConfig;
      2. using Firebase.Crashlytics;

2. 確認您已匯入適當的 Firebase 套件：

   1. 透過下列任一方式匯入適當的套件：
      1. 將 Firebase Unity SDK 新增為 .unitypackage 或
      2. 查看並執行「其他 Unity 安裝選項」中其中一個替代選項。
   2. 確認專案和 EDM4U 中的每個 Firebase 產品：
      • 版本相同
      • 安裝為 .unitypackage 獨有，或僅透過 Unity 套件管理員安裝。

3. 如果您已將「10.0.0」之前版本的 Firebase Unity SDK 匯入為 .unitypackage，則 Firebase Unity SDK ZIP 封存檔包含同時支援 .NET 3.x 和 .NET 4.x 的套件。請確認您在專案中僅納入相容的 .NET Framework 層級：

   1. 如要瞭解 Unity 編輯器和 .NET Framework 等級版本之間的相容性，請參閱「將 Firebase 新增至 Unity 專案」。
   2. 如果您不小心將 Firebase 套件匯入錯誤的 .NET Framework 層級，或是需要從使用 .unitypackage 改成其中一種其他 Unity 安裝選項，最簡單的方式就是按照本遷移章節中提及的方法移除所有 Firebase 套件，然後重新匯入所有 Firebase 套件。

4. 請檢查編輯器是否正在重建專案，並確認嘗試播放的內容反映專案的最新狀態：

   1. 根據預設，只要偵測到素材資源或設定變更，Unity 編輯器就會設定為重新建構。
   2. 這可能是因為這項功能已停用，而 Unity 編輯器可能設為手動重新整理/重新編譯。請調查這個問題，如果有這種情況，請嘗試手動重新整理。

Play 模式執行階段錯誤

如果遊戲已開始執行，但執行時在 Firebase 發生問題，請嘗試下列做法：

確認已在 Mac OS 的「安全性與隱私權」中核准 Firebase 套件

如果是在 Mac OS 的編輯器中啟動您的遊戲，畫面上會出現「FirebaseCppApp-<version>.bundle，因此無法開啟，因為開發人員無法驗證該套件」。您必須在 Mac 的「安全性與隱私權」選單中核准該套件檔案。

做法是依序點選「Apple」圖示 >「系統偏好設定」>「安全性與隱私權」。

安全性選單大約有一半的頁面會顯示「FirebaseCppApp-<version>.bundle」，表示該程式並非由已識別的開發人員提供，因此無法使用。

按一下標示「仍允許」的按鈕。

注意： 除非你信任來源、自行撰寫，且瞭解檔案用途和遭系統標記的原因，否則請勿核准這類檔案。

返回 Unity，再次按下「Play」。

則會看到類似第一個警告的警示：

按下「開啟」，你的程式可以繼續操作；系統不會再向你詢問這個特定檔案的問題。

請確認您的專案包含有效的設定檔，而且正在使用有效的設定檔

1. 在「File」>「Build Settings」中，確認版本設定適用於所需目標 (iOS 或 Android)。如需更完整的討論內容，請參閱 Unity 建構設定說明文件。
2. 下載應用程式的設定檔 (Android 為 google-services.json，iOS 為 GoogleService-Info.plist)，然後在 Firebase 控制台中依序前往「專案設定」>「你的應用程式」建立目標： 如果你已在專案中刪除這些檔案，請將檔案從專案中刪除，並以最新版本取代，並確認這些檔案的拼寫方式與上述版本完全相同，而且不含「(1)」或附加在檔案名稱上的其他數字。
3. 如果控制台顯示與 Assets/StreamingAssets/ 中的檔案有關的訊息，請確認沒有任何主控台訊息指出 Unity 無法在其中編輯檔案
4. 請確認已產生 Assets/StreamingAssets/google-services-desktop.json，且與下載的設定檔相符。
   • 如果系統未自動產生目錄，且 StreamingAssets/ 不存在，請在 Assets 目錄中手動建立目錄。
   • 檢查 Unity 是否已產生 google-services-desktop.json。

確保每個 Firebase 產品和 EDM4U 都只透過 .unitypackage 或 Unity 套件管理工具安裝

1. 請同時檢查 Assets/ 資料夾和 Unity Package Manager，確認已透過任一方法單獨安裝 Firebase SDK 和 EDM4U。
2. 部分 Google 開發的外掛程式 (例如 Google Play) 和第三方外掛程式可能會依附 EDM4U。這些外掛程式可能在 .unitypackage 或 Unity Package Manager (UPM) 套件中納入 EDM4U。請確保專案中只有一份 EDM4U 的副本。如果有任何 UPM 套件需要使用 EDM4U，建議您僅保留 UPM 版本的 EDM4U (可在 Unity Archive 的 Google API 頁面上查看)。

確認專案中的所有 Firebase 產品皆相同版本。

1. 如果您是透過 .unitypackage 安裝 Firebase SDK，請檢查 Assets/Firebase/Plugins/x86_64/ 下的所有 FirebaseCppApp 程式庫是否都具有相同版本。
2. 如果 Firebase SDK 是透過 Unity Package Manager (UPM) 安裝，請開啟「Windows」>「套件管理員」，搜尋「Firebase」，確認所有 Firebase 套件都使用同一個版本。
3. 如果您的專案含有不同版本的 Firebase SDK，建議您先徹底移除所有 Firebase SDK，然後再次安裝所有 Firebase SDK 版本相同的版本。最簡潔的方式，就是按照本遷移章節中提及的方法，移除所有 Firebase 套件。

解析器和目標裝置版本錯誤

如果您的遊戲可在編輯器中運作 (已根據您選擇的建構目標進行設定)，接著請確認 Unity 的 External Dependency Manager (EDM4U) 已正確設定並正常運作。

注意： 您會在 Unity Firebase 設定程序中新增 EDM4U。

EDM4U GitHub 存放區提供這部分程序的逐步指南，建議您先檢閱並遵循相關步驟，然後再繼續進行。

「Single Dex」問題和壓縮 (若使用 Cloud Firestore，則為 Mandatory)

建構 Android 應用程式時，您可能會遇到與單一 dex 檔案相關的建構失敗問題。系統會顯示類似以下的錯誤訊息 (如果專案設為使用 Gradle 建構系統)：

Cannot fit requested classes in a single dex file.

.dex 檔案可用來保存一組類別定義及相關的 Android 應用程式連接資料。單一 dex 檔案只能參照 65,536 個方法；如果專案中所有 Android 程式庫的方法總數超過此上限，建構作業就會失敗。

您可依序套用以下兩個步驟；只有在壓縮無法解決問題時，才啟用 Multidex。

啟用壓縮功能

Unity 於 2017.2 年推出壓縮功能，以便去除未使用的程式碼，可減少單一 dex 檔案中參照的方法總數。* 依序前往「Player Settings」>「Android」>「Publish Settings」>「Minify」，即可找到這個選項。* 選項可能因 Unity 版本而異，請參閱官方 Unity 說明文件。

啟用 Multidex

啟用壓縮功能後，如果參照的方法數量仍超出限制，則可選擇啟用 multidex。在 Unity 中有許多方法可以達到這個效果：

• 如果已啟用「Player Settings」下方的「Custom Gradle Template」，請修改 mainTemplate.gradle。
• 如果您使用 Android Studio 建立匯出的專案，請修改模組層級的 build.gradle 檔案。

詳情請參閱 Multidex 使用手冊。

瞭解及修正目標裝置執行階段錯誤

如果您的遊戲可在編輯器中運作，且可針對目標裝置建構及安裝遊戲，但遇到執行階段錯誤，請檢查並調查裝置上產生的記錄。

本節將說明如何調查記錄中是否存在潛在錯誤，以及一個只會在裝置或模擬器的執行階段發生的錯誤。

Android

模擬器

• 檢查模擬器主控台中顯示的記錄，或檢視「Logcat」視窗。

裝置

熟悉 ADB 和 ADB Logcat 及其使用方式。

• 雖然您可以使用指令列環境的各種工具篩選輸出內容，但不妨改為查看 Logcat 的「選項」。

• 以簡潔的插入畫面啟動 ADB 工作階段的簡單方法是：

  adb logcat -c && adb logcat <OPTIONS>
  

  其中 OPTIONS 是您傳遞指令列用於篩選輸出內容的旗標。

透過 Android Studio 使用 Logcat

透過 Android Studio 使用 Logcat 時，您可以提供其他搜尋工具，讓搜尋更有效率。

iOS

檢查記錄

如果執行的是實體裝置，請將裝置連接至電腦。檢查 Xcode 中的 lldb。

Swift 相關問題

如果您遇到提及 Swift 的錯誤記錄，請參閱「External Dependency Manager for Unity」一節。

後續步驟

如果您的遊戲仍有編譯、建構或執行 Firebase 相關問題，請查看 Firebase SDK for Unity 問題頁面，並考慮提交新問題。如要進一步瞭解其他選項，請前往 Firebase 支援頁面。