開始使用適用於 Apple 平台的 Crashlytics

本指南說明如何在 Apple 平台應用程式 (例如 iOS 應用程式) 中開始使用 Firebase Crashlytics。

在應用程式中設定 Firebase Crashlytics SDK 後，您可以在 Firebase 控制台中取得完整的當機報告。有了 Apple 平台適用的 Crashlytics，您就能取得當機和非致命錯誤的報告。

Help me use Firebase in my app.
1. Make sure that **Firebase agent skills** are installed and updated. For Claude Code, Codex, or Cursor agents, help me install the Firebase plugin. For other agents, run `npx skills add firebase/agent-skills`.  Always try to use **Firebase agent skills** for Firebase-related tasks.
2. Help me set up Firebase Crashlytics for my app.

事前準備

如要設定 Crashlytics，您必須在 Firebase 控制台和 IDE 中執行多項工作，例如新增 Firebase 設定檔和 Crashlytics SDK。如要完成設定，您必須強制測試當機，將第一份當機報告傳送至 Firebase。

1. 如果您尚未將 Firebase 新增至 Apple 專案，請先新增。如果沒有 Apple 應用程式，可以下載範例應用程式。

2. 建議：如要自動取得當機前使用者動作記錄，瞭解導致當機或非致命事件的使用者動作，請在 Firebase 專案中啟用 Google Analytics。

   • 如要建立新的 Firebase 專案，請在專案建立工作流程中啟用 Google Analytics。

   • 如果您使用的現有 Firebase 專案未啟用 Google Analytics，可以在 Firebase 控制台的「settings 設定」>「整合」頁面啟用。

   請注意，除了 watchOS 以外，Crashlytics 支援的所有 Apple 平台都提供當機前使用者動作記錄。

步驟 1：在應用程式中加入 Crashlytics SDK

使用 Swift Package Manager 安裝及管理 Firebase 依附元件。

1. 在 Xcode 中保持開啟應用程式專案，然後依序點選「File」(檔案) 和「Add Packages」(新增 Package)。
2. 系統提示時，請新增 Firebase Apple 平台 SDK 存放區：

  https://github.com/firebase/firebase-ios-sdk.git

3. 選擇 Crashlytics 程式庫。
4. 如要使用當機前使用者動作記錄，請一併將 Google Analytics 專用 Firebase SDK 新增至應用程式。請確認 Firebase 專案已啟用 Google Analytics。
5. 在目標建構設定的「Other Linker Flags」部分，新增 -ObjC 標記。
6. (僅限 macOS) 在 Info.plist 中，新增 NSApplicationCrashOnExceptions 鍵，並將其設為 YES。
7. 完成後，Xcode 會自動開始在背景解析及下載依附元件。

接著，設定 Firebase 模組：

1. 在 App struct 或 UIApplicationDelegate 中匯入 Firebase 模組：

   Swift

   import Firebase

   Objective-C

   @import Firebase;

2. 設定 FirebaseApp 共用例項，通常是在應用程式委派的 application(_:didFinishLaunchingWithOptions:) 方法中：

   Swift

   // Use the Firebase library to configure APIs.
   FirebaseApp.configure()

   Objective-C

   // Use the Firebase library to configure APIs.
   [FIRApp configure];

步驟 2：設定 Xcode 以自動上傳 dSYM 檔案

為產生人類可讀的當機報告，Crashlytics 需要專案的偵錯符號 (dSYM) 檔案。下列步驟說明如何設定 Xcode，以便在每次建構應用程式時，自動產生 dSYM、處理並上傳檔案。

1. 開啟專案的 Xcode 工作區，然後在左側導覽器中選取專案檔案。

2. 從「TARGETS」清單中選取主要建構目標。

3. 按一下「Build Settings」分頁標籤，然後完成下列步驟，讓 Xcode 為您的版本產生 dSYM。

   1. 按一下「全部」，然後搜尋 debug information format。

   2. 將所有建構類型的「Debug Information Format」設為 DWARF with dSYM File。

4. 按一下「Build Phases」分頁標籤，然後完成下列步驟，讓 Xcode 處理 dSYM 並上傳檔案。

   1. 依序點按 add >「New Run Script Phase」。

      請確認這個新的「Run Script」階段是專案的最後一個建構階段，否則 Crashlytics 無法正確處理 dSYM。

   2. 展開新的「Run Script」部分。

   3. 在指令碼欄位 (位於「Shell」標籤下方) 中，新增下列執行指令碼。

      這個指令碼會處理專案的 dSYM 檔案，並將檔案上傳至 Crashlytics。

      "${BUILD_DIR%/Build/*}/SourcePackages/checkouts/firebase-ios-sdk/Crashlytics/run"

   4. 在「Input Files」(輸入檔案) 區段中，新增下列檔案的位置路徑：

      ${DWARF_DSYM_FOLDER_PATH}/${DWARF_DSYM_FILE_NAME}

      ${DWARF_DSYM_FOLDER_PATH}/${DWARF_DSYM_FILE_NAME}/Contents/Resources/DWARF/${PRODUCT_NAME}

      ${DWARF_DSYM_FOLDER_PATH}/${DWARF_DSYM_FILE_NAME}/Contents/Info.plist

      $(TARGET_BUILD_DIR)/$(UNLOCALIZED_RESOURCES_FOLDER_PATH)/GoogleService-Info.plist

      $(TARGET_BUILD_DIR)/$(EXECUTABLE_PATH)

      如果專案建構設定中有 ENABLE_USER_SCRIPT_SANDBOXING=YES 和 ENABLE_DEBUG_DYLIB=YES，請加入下列內容：

      ${DWARF_DSYM_FOLDER_PATH}/${DWARF_DSYM_FILE_NAME}/Contents/Resources/DWARF/${PRODUCT_NAME}.debug.dylib

      瞭解為何需要這些檔案的位置

      Xcode 會在指定位置尋找這些輸入檔案，確保建構檔案可供執行指令碼使用。此外，如果啟用「User Script Sandboxing」，Xcode 只會允許執行指令碼存取「Input Files」中指定的檔案。

      • 提供專案 dSYM 檔案的位置，Crashlytics 就能處理 dSYM。
      • 提供應用程式建構的 GoogleService-Info.plist 檔案位置，Crashlytics 就能將 dSYM 與 Firebase 應用程式建立關聯。
      • 提供應用程式執行檔的位置，可讓執行指令碼避免重複上傳相同的 dSYM。請注意，系統不會上傳應用程式二進位檔。

如要進一步瞭解 dSYM 檔案和 Crashlytics (包括如何手動上傳 dSYM 檔案)，請參閱「取得去模糊化的當機報告」。

步驟 3：強制測試當機以完成設定

您需要強制測試當機，才能完成設定 Crashlytics，並在 Firebase 控制台的 Crashlytics 資訊主頁中查看初始資料。

1. 在應用程式中加入程式碼，強制造成測試當機。

   您可以使用下列程式碼，在應用程式中加入按鈕，按下後就會造成當機。按鈕標籤為「Test Crash」。

   SwiftUI

   Button("Crash") {
     fatalError("Crash was triggered")
   }

   UIKit

   Swift

   import UIKit
   
   class ViewController: UIViewController {
     override func viewDidLoad() {
         super.viewDidLoad()
   
         // Do any additional setup after loading the view, typically from a nib.
   
         let button = UIButton(type: .roundedRect)
         button.frame = CGRect(x: 20, y: 50, width: 100, height: 30)
         button.setTitle("Test Crash", for: [])
         button.addTarget(self, action: #selector(self.crashButtonTapped(_:)), for: .touchUpInside)
         view.addSubview(button)
     }
   
     @IBAction func crashButtonTapped(_ sender: AnyObject) {
         let numbers = [0]
         let _ = numbers[1]
     }
   }

   Objective-C

   #import "ViewController.h"
   
   @implementation ViewController
   ‐ (void)viewDidLoad {
       [super viewDidLoad];
   
       // Do any additional setup after loading the view, typically from a nib.
   
       UIButton* button = [UIButton buttonWithType:UIButtonTypeRoundedRect];
       button.frame = CGRectMake(20, 50, 100, 30);
       [button setTitle:@"Test Crash" forState:UIControlStateNormal];
       [button addTarget:self action:@selector(crashButtonTapped:)
           forControlEvents:UIControlEventTouchUpInside];
       [self.view addSubview:button];
   }
   
   ‐ (IBAction)crashButtonTapped:(id)sender {
       @[][1];
   }
   
   @end

2. 在 Xcode 中建構並執行應用程式，並中斷 Xcode 偵錯工具的連線。

   1. 按一下 play_arrow「Build and then run the current scheme」，在測試裝置或模擬器上建構應用程式。

   2. 等到應用程式執行後，按一下 stop「Stop running the scheme or action」，關閉應用程式的初始執行個體。這個初始執行個體包含會干擾 Crashlytics 的偵錯工具。

3. 強制執行測試當機，以便傳送應用程式的第一份當機報告：

   1. 從測試裝置或模擬器的主畫面開啟應用程式。

   2. 在應用程式中，按下使用上述程式碼新增的「Test Crash」按鈕。

   3. 應用程式當機後，請從 Xcode 再次執行，以便將當機報告傳送至 Firebase。

4. 在 Firebase 控制台中，依序前往「DevOps & Engagement」(開發運作與參與度) >「Crashlytics dashboard」(資訊主頁)，查看測試當機報告。

   如果重新整理控制台後，五分鐘內仍未看到測試當機事件，請啟用偵錯記錄檔，查看應用程式是否傳送當機報告。

大功告成！Crashlytics 現在會監控應用程式是否當機。 前往Crashlytics 資訊主頁，查看及調查所有報表和統計資料。

後續步驟

• 自訂當機報告設定：新增選擇加入報告、記錄、金鑰和非致命錯誤追蹤。

• 將資料匯出至 BigQuery 或 Cloud Logging，即可使用進階分析和功能，例如查詢資料、建立自訂資訊主頁，以及設定自訂快訊。