App Center 崩潰（Unity）

2025-05-06

這很重要

Visual Studio App Center 於 2025 年 3 月 31 日淘汰，但分析和診斷功能除外，這些功能將持續支援到 2026 年 6 月 30 日。瞭解更多資訊。

App Center Crashes 會在每次應用程式當機時自動產生當機記錄，並記錄到裝置儲存。當使用者再次啟動應用程式時，SDK 會將當機報告傳送至 App Center。收集崩潰資料適用於 Beta 和正式上線的應用程式，也就是提交到 Google Play 的崩潰報告。當機記錄包含協助您修正當機的重要資訊。

如果您尚未在應用程式中設定 SDK，請遵循 Unity 用戶入門一節中的指示。

iOS 上的當機記錄需要符號。若要啟用符號，請參閱 App Center 診斷檔，其中說明如何為您的應用程式提供符號。

這很重要

適用於 Unity 的崩潰 SDK 不支援 UWP。此頁面中的指示僅涵蓋Android和iOS。

備註

如果您已連結調試程式，SDK 將不會轉送任何當機記錄。當應用程式當機時，請確保偵錯工具未被附加。

備註

如果您已在 Enable CrashReport APIPlayerSettings 中啟用，SDK 將不會收集損毀記錄。

產生測試當機

App Center 當機提供 API 來產生測試當機，以便輕鬆測試 SDK。此 API 會檢查偵錯與發行組態。因此，您只能在偵錯時使用它，因為它不適用於發行應用程式。

Crashes.GenerateTestCrash();

備註

這個方法只適用於開啟 開發版本 設定。

取得先前當機的詳細資訊

App Center Crashes 有兩個 API，可以在應用程式當機時提供更多資訊。

應用程式在上一個會話中是否收到記憶體不足的警告？

在啟動 SDK 之後，您可以隨時檢查應用程式是否在上一個工作階段中收到記憶體警告：

bool hadLowMemoryWarning = Crashes.HasReceivedMemoryWarningInLastSessionAsync().Result;

備註

這個方法無法在中 Awake()運作。

備註

在某些情況下，記憶體不足的裝置無法傳送事件。

應用程式在上一個工作階段中是否當機？

在啟動 SDK 之後，您可以隨時檢查應用程式是否在上一次啟動中當機：

bool didAppCrash = await Crashes.HasCrashedInLastSessionAsync();

如果您想要在發生當機后調整應用程式的行為或 UI，呼叫 HasCrashedInLastSessionAsync 會很有用。有些開發人員會顯示其他使用介面來向使用者道歉，或者希望在發生當機後與他們取得聯絡。

上次當機的詳細數據

如果您的應用程式先前當機，您可以取得上次當機的詳細數據。

ErrorReport crashReport = await Crashes.GetLastSessionCrashReportAsync();

此 API 最常見的使用案例是當用戶實作其自定義損毀委派或接聽程式時。

自訂 App Center 當機的使用方式

App Center 當機提供回呼，讓開發人員能在將當機日誌傳送至 App Center 前後採取其他動作。

備註

在 App Center 啟動之前設定回呼，例如在 Awake 方法中，因為 App Center 會在啟動後立即開始處理當機。

是否應該處理當機？

如果您想決定是否要處理特定當機，請設定以下回呼函數。例如，您可能會想要忽略系統層級當機，而不會傳送至 App Center。

Crashes.ShouldProcessErrorReport = (ErrorReport report) =>
{
     // Check the report in here and return true or false depending on the ErrorReport.
    return true;
};

如果用戶隱私權對於您很重要，您可能會想要先取得使用者確認，再將當機報告傳送至 App Center。 SDK 會公開回呼，告知 App Center 損毀在傳送任何損毀報告之前等候用戶確認。

如果您的程式代碼使用此回呼，您必須負責取得使用者的確認。其中一個選項是透過具有下列其中一個選項的對話框提示： 永遠傳送、傳送和 不要傳送。根據輸入，您將告訴 App Center 損毀要執行的動作，然後會據以處理損毀。

備註

SDK 不會顯示此對話框，應用程式必須提供自己的 UI 以要求使用者同意。

下列回呼顯示如何告訴 SDK 等到使用者確認之後，再傳送錯誤回報：

Crashes.ShouldAwaitUserConfirmation = () =>
{
    // Build your own UI to ask for user consent here. SDK doesn't provide one by default.

    // Return true if you built a UI for user consent and are waiting for user input on that custom UI, otherwise false.
    return true;
};

如果回呼傳 true回，您必須使用下列 API 取得使用者許可權，並將 SDK 訊息給結果：

// Depending on the user's choice, call Crashes.NotifyUserConfirmation() with the right value.
Crashes.NotifyUserConfirmation(UserConfirmation.DontSend);
Crashes.NotifyUserConfirmation(UserConfirmation.Send);
Crashes.NotifyUserConfirmation(UserConfirmation.AlwaysSend);

例如，您可以參考我們的自定義對話範例。

取得當機記錄檔傳送狀態的相關資訊

有時，您想要知道應用程式當機狀態。常見的使用案例是顯示使用者介面，以通知使用者應用程式正在提交當機報告。另一個案例是您想要調整應用程式的行為，以確保在重新啟動后不久就能提交當機記錄。 App Center 當機提供三個不同的回呼，您可以發出通知，以得知發生什麼情況：

SDK 傳送當機記錄檔之前，將會調用下列回呼函式

Crashes.SendingErrorReport += (errorReport) =>
{
    // Your code, e.g. to present a custom UI.
};

如果我們在端點上有網路問題或中斷，而且您重新啟動應用程式， SendingErrorReport 則會在進程重新啟動后再次觸發。

在 SDK 成功傳送當機記錄檔後，將會執行下列回呼函數

Crashes.SentErrorReport += (errorReport) =>
{
    // Your code, e.g. to hide the custom UI.
};

如果 SDK 無法傳送當機記錄檔，將會叫用下列回呼

Crashes.FailedToSendErrorReport += (errorReport, exception) =>
{
    // Your code goes here.
};

FailedToSendErrorReport接收表示發生無法復原的錯誤，例如發生 4xx 碼。例如， 401 表示 appSecret 錯誤。

若是網路問題，則不會觸發此回呼。在此情況下，SDK 會持續重試（並在網路連線關閉時暫停重試）。

將附件新增至當機或未處理的例外狀況報告

您也可以選擇性地將二進位和文字附件新增至當機或未處理的例外狀況報告。 SDK 會連同報表一起傳送它們，以便您可以在 App Center 入口網站中看到它們。在傳送預存報表之前，會立即叫用下列回呼。如果當機，它會在下一次應用程式啟動時發生。針對未處理的例外狀況，您必須加入加入以傳送附件。請確定附件檔案未被命名為 minidump.dmp，因為該名稱是保留給迷你傾印檔案使用的。以下是如何將文字和影像附加至報表的範例：

Crashes.GetErrorAttachments = (ErrorReport report) =>
{
    // Your code goes here.
    return new ErrorAttachmentLog[]
    {
        ErrorAttachmentLog.AttachmentWithText("Hello world!", "hello.txt"),
        ErrorAttachmentLog.AttachmentWithBinary(Encoding.UTF8.GetBytes("Fake image"), "fake_image.jpeg", "image/jpeg")
    };
};

當機與屬性 IsCrash 的報表中未處理的例外狀況有所區別。這個屬性在發生當機時為 true，在其他情況下為 false。

備註

大小限制適用於目前為 7 MB 的附件。嘗試傳送較大的附件將會觸發錯誤。

備註

GetErrorAttachments 在主線程上被叫用，且不會將工作分割到各個幀。若要避免封鎖遊戲迴圈，請勿在此回呼中執行任何長時間執行的工作。

在運行時間啟用或停用 App Center 當機

您可以在執行時間啟用和停用 App Center 崩潰功能。如果您停用它，SDK 將不會針對應用程式執行任何當機報告。

Crashes.SetEnabledAsync(false);

若要再次啟用 App Center 異常回報功能，請使用相同的 API，但傳遞 true 作為參數。

Crashes.SetEnabledAsync(true);

您不需要等候此呼叫，即可讓其他 API 呼叫（例如） IsEnabledAsync保持一致。

狀態會保存在裝置跨應用程式啟動時的記憶體中。

檢查應用程式中心崩潰是否已啟用

您還可以檢查 App Center Crashes 是否已啟用：

bool isEnabled = await Crashes.IsEnabledAsync();

Unity 中已處理的例外狀況

App Center 也可讓您使用 Unity 中已處理的例外狀況來追蹤錯誤。若要這樣做，請使用 TrackError 方法：

try {
    // your code goes here.
} catch (Exception exception) {
    Crashes.TrackError(exception);
}

如需有關您的錯誤的進一步背景資訊，您也可以將屬性添加到您的錯誤。傳遞屬性做為字串的字典。這個步驟是選擇性的。

try {
    // your code goes here.
} catch (Exception exception) {
    var properties = new Dictionary<string, string>
    {
        { "Category", "Music" },
        { "Wifi", "On" }
    };
    Crashes.TrackError(exception, properties);
}

您也可以選擇性地將二進位和文字附件新增至已處理的錯誤報告。傳遞附件作為ErrorAttachmentLog物件陣列，如下列範例所示。

try {
    // your code goes here.
} catch (Exception exception) {
    var attachments = new ErrorAttachmentLog[]
    {
        ErrorAttachmentLog.AttachmentWithText("Hello world!", "hello.txt"),
        ErrorAttachmentLog.AttachmentWithBinary(Encoding.UTF8.GetBytes("Fake image"), "fake_image.jpeg", "image/jpeg")
    };
    Crashes.TrackError(exception, attachments: attachments);
}

Unity 中未處理的例外狀況

報告未處理的例外狀況

根據預設，App Center SDK 不會報告應用程式中未處理且不導致致命崩潰的例外狀況。若要啟用這項功能，請呼叫下列方法：

Crashes.ReportUnhandledExceptions(true);

呼叫此 API 之後，App Center 會將所有未處理的例外狀況記錄為 App Center 入口網站中的問題，類似於先前所述的已處理例外狀況。若要停用這項功能，請呼叫與參數傳遞 false 相同的 API。

Crashes.ReportUnhandledExceptions(false);

備註

App Center SDK 偵測到的某些未處理的例外狀況會顯示為 App Center UI 中的錯誤。這是因為 Unity 預設會攔截未處理的例外狀況，這表示應用程式不會結束且不會被視為當機。

將附件新增至未處理的例外狀況報告

根據預設，App Center SDK 不會在未處理的例外狀況上啟用附件。若要啟用這項功能，請將 enableAttachmentsCallback 方法的 ReportUnhandledExceptions 布林參數設定為 true：

Crashes.ReportUnhandledExceptions(true, true);

然後，您可以藉由實作 GetErrorAttachments 回呼，選擇性地將附件新增至未處理的例外狀況報告。

報告 NDK 當機問題

報告當機

若要在 App Center 中接收適當的當機報告，請先遵循上述指示，確定您已設定 App Center 損毀 SDK。

建置Breakpad程式庫

接下來，您必須遵循官方 Google Breakpad for Android 自述檔中列出的指示，包含並編譯 Google Breakpad。若要在 Unity 中使用，請將二進位檔包含在您的應用程式中。

備註

App Center SDK 預設不會組合 Google Breakpad。

附加例外狀況處理程式

一旦您包含Google Breakpad，請附加NDK Crash Handler：

/* Attach NDK Crash Handler. */
var minidumpDir = Crashes.GetMinidumpDirectoryAsync();
setupNativeCrashesListener(minidumpDir.Result);

...

[DllImport("YourLib")]
private static extern void setupNativeCrashesListener(string path);

setupNativeCrashesListener 方法是您必須在 C/C++ 中實作的原生方法。

#include <android/log.h>
#include "google-breakpad/src/client/linux/handler/exception_handler.h"
#include "google-breakpad/src/client/linux/handler/minidump_descriptor.h"

static google_breakpad::ExceptionHandler exception_handler(google_breakpad::MinidumpDescriptor(), NULL, dumpCallback, NULL, true, -1);

/**
 * Registers breakpad as the exception handler for NDK code.
 * @param path minidump directory path returned from Crashes.GetMinidumpDirectoryAsync()
 */
extern "C" void setupNativeCrashesListener(const char *path) {
    google_breakpad::MinidumpDescriptor descriptor(path);
    exception_handler.set_minidump_descriptor(descriptor);
}

用於疑難解答的位置 dumpCallback ：

/*
 * Triggered automatically after an attempt to write a minidump file to the breakpad folder.
 */
static bool dumpCallback(const google_breakpad::MinidumpDescriptor &descriptor,
                         void *context,
                         bool succeeded) {

    /* Allow system to log the native stack trace. */
    __android_log_print(ANDROID_LOG_INFO, "YourLogTag",
                        "Wrote breakpad minidump at %s succeeded=%d\n", descriptor.path(),
                        succeeded);
    return false;
}

這些方法正確設定之後，應用程式會在重新啟動時自動將小型轉儲傳送至 App Center。進行故障排除時，您可以使用詳細記錄來檢查應用程式重新啟動後是否傳送小型傾印。

備註

App Center 會使用保留名稱minidump.dmp來處理迷你轉儲附件。請務必為附件提供不同的名稱，除非它是小型傾印檔案，以便我們可以正確處理它。

警告

Breakpad 中有已知的錯誤，導致無法在 x86 模擬器上捕捉當機。

符號

如需有關損毀處理的詳細資訊，請參閱診斷檔。

共用方式為

App Center 崩潰 （Unity）