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

簡介

以下是使用 Unity 專用 Firebase SDK 為 Unity 遊戲偵錯編譯和建構程序的指南。以下說明如何針對新平台設定及建構遊戲,或在更新後,瞭解如何調查及解決許多更常見的問題。這些錯誤的排列順序,是依據這些錯誤在程序中可能發生的時間。請依序查詢這些 ID 並解決問題。

除了本文件外,請參閱 Unity 版 Firebase 常見問題,進一步瞭解相關資訊。

遊戲模式編譯問題

在嘗試啟動行動裝置建構作業之前,您可以在編輯器中進行測試,這時可能會發生第一類建構問題。本節著重在 Play 模式之前和期間發生的所有 Firebase 錯誤。

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

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

如果編輯器和編譯器無法找到必要的類型、類別、方法和成員,就會發生許多 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 Package Manager 安裝。
  3. 如果您匯入的 Firebase Unity SDK 為 10.0.0 以下版本的 .unitypackage,則 Firebase Unity SDK ZIP 封存檔會包含 .NET 3.x 和 .NET 4.x 的支援套件。請確認您在專案中僅納入相容的 .NET Framework 層級:

    1. 如要瞭解 Unity 編輯器版本與 .NET 架構層級之間的相容性,請參閱「將 Firebase 新增至您的 Unity 專案」一文。
    2. 如果您不小心將 Firebase 套件匯入錯誤的 .NET Framework 層級,或是需要從使用 .unitypackage 改成其中一種其他 Unity 安裝選項,最簡單的方式就是按照本遷移章節中提及的方法移除所有 Firebase 套件,然後重新匯入所有 Firebase 套件。
  4. 請確認編輯器是否正在重新建構專案,且您嘗試播放的內容反映了專案的最新狀態:

    1. 根據預設,Unity 編輯器會在偵測到資產或設定變更時重建。
    2. 這項功能可能已停用,且 Unity 編輯器已設為「手動重新整理/重新編譯」。請調查這個問題,如果是這種情況,請嘗試手動重新整理。

執行模式執行階段錯誤

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

請務必在「安全性與隱私權」在 Mac OS 上

如果是在 Mac OS 的編輯器中啟動您的遊戲,系統會顯示「FirebaseCppApp-<version>.bundle 無法完成開啟,因為開發人員無法驗證。」您必須在 Mac 的「安全性與」中核准該特定套件檔案隱私設定選單。

如要這麼做,請依序點選「Apple 圖示」>系統偏好設定 >安全性和隱私權

在安全性選單中,頁面下方約一半處有一個部分,指出「FirebaseCppApp-<version>.bundle」已遭封鎖,因為該檔案並非來自已認證的開發人員。」

按一下「還是允許」按鈕。

c35166e224cce720.png

返回 Unity,然後再次按下「Play」

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

5ad9ddb0d3a52892.png

按下「Open」,該程式即可繼續操作。系統不會再向你詢問這個特定檔案。

確認專案包含並使用有效的設定檔

  1. 在「檔案」>「Android」中,請確定您已為目標目標 (iOS 或 Android) 完成建構設定版本設定。如需更完整的討論內容,請參閱 Unity 建構設定說明文件
  2. 請在 Firebase 控制台的 專案設定 > 您的應用程式中,下載應用程式的設定檔 (Android 版為 google-services.json,iOS 版為 GoogleService-Info.plist) 和建構目標: 如果您已擁有這些檔案,請在專案中刪除這些檔案,並用最新版本取代,確保檔案名稱的拼法與上述內容完全一致,且檔名中沒有附加「(1)」或其他數字。
  3. 如果控制台包含 Assets/StreamingAssets/ 中檔案的相關訊息,請確認控制台中沒有任何訊息指出 Unity 無法編輯該處的檔案
  4. 請確認系統產生的 Assets/StreamingAssets/google-services-desktop.json 與下載的設定檔相符。
    • 如果系統未自動產生,且 StreamingAssets/ 不存在,請在 Assets 目錄中手動建立目錄。
    • 檢查 Unity 是否已產生 google-services-desktop.json

請確認所有 Firebase 產品和 EDM4U 都是透過 .unitypackage 或 Unity Package Manager 安裝

  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. 如果是透過 Unity Package Manager (UPM) 安裝 Firebase SDK,請依序開啟「Windows」>「Package Manager」,搜尋「Firebase」,並確認所有 Firebase 套件皆為相同版本。
  3. 如果您的專案含有不同版本的 Firebase SDK,建議您先徹底移除所有 Firebase SDK,然後再次安裝所有 Firebase SDK 版本相同的版本。最簡單的方法是透過這個遷移專區中提到的方法移除每個 Firebase 套件。

解析器和目標裝置建構錯誤

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

EDM4U GitHub 存放區包含逐步指南,您應先詳閱並遵循指南中的說明,再繼續進行。

「單身」問題和壓縮 (若使用 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」>「Player Settings」>Android >發布設定 >縮小。 * 不同版本的 Unity 可能提供不同的選項,請參閱 Unity 官方說明文件。

啟用 Multidex

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

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

詳情請參閱 multidex 使用者指南

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

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

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

Android

模擬工具

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

裝置

熟悉 adbadb logcat 的使用方式。

  • 您可以使用指令列環境的各種工具篩選輸出內容,也可以考慮查看 Logcat 的選項
  • 如要以全新狀態啟動 ADB 工作階段,可以採取以下簡單做法:

    adb logcat -c && adb logcat <OPTIONS>
    

    其中 OPTIONS 是您傳遞指令列以篩選輸出的任意標記。

透過 Android Studio 使用 Logcat

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

iOS

檢查記錄檔

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

Swift 相關問題

如果您在錯誤記錄中看到 Swift 相關內容,請參閱「Unity 的外部依附元件管理工具」一節。

後續步驟

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