在 Crashlytics 資訊主頁 (網頁) 取得淺顯易懂的當機報告

選取平台： iOS+ Android Web Flutter Unity


網頁應用程式會在正式環境中編譯、壓縮及混淆程式碼名稱，以最佳化網路套件。如果沒有來源對應，Crashlytics 資訊主頁中的當機報告會顯示經過壓縮和模糊處理的堆疊追蹤。

如要將堆疊追蹤去模糊化，並在 Error Reporting 中顯示原始檔案名稱和行號，請使用 Firebase CLI 指令，將來源對應 (.js.map 檔案) 上傳至 Firebase。

必要條件

上傳來源對應前，請確認您已安裝 Firebase CLI 15.35.0 以上版本。瞭解如何安裝或更新 Firebase CLI。

步驟 1：在框架建構中啟用來源對應產生功能

設定前端架構或繫結器，在應用程式建構程序中產生正式版來源 (.js.map) 檔案：

Angular

在 Angular 中，您必須在 angular.json 工作區檔案中設定 sourceMap 選項，或傳遞 --source-map CLI 覆寫旗標：

方法 1 (建議)：修改 angular.json

開啟 angular.json 檔案，找出要指定的特定建構設定 (例如 development 或 production)。在 options 或 configurations 區塊下設定 sourceMap 參數：

"projects": {
  "APP_NAME": {
    "architect": {
      "build": {
        "options": {
          "sourceMap": true
        },
        "configurations": {
          "production": {
            "sourceMap": {
              "scripts": true,
              "vendor": false
            }
          }
        }
      }
    }
  }
}

方法 2：指令列覆寫

如果只需要用於一次性驗證建構或偵錯工作階段的來源對應，請直接將 --source-map 旗標附加至 Angular CLI 建構指令：

ng build --configuration production --source-map

Next.js

更新 next.config.ts (或 next.config.js) 檔案，將 productionBrowserSourceMaps 設為 true，在正式版建構期間啟用瀏覽器來源對應產生功能：

// next.config.ts
import type { NextConfig } from "next";

const nextConfig: NextConfig = {
  // Enable browser source map emission for Crashlytics stack trace de-obfuscation
  productionBrowserSourceMaps: true,
  // ... rest of your Next.js configuration
};

export default nextConfig;

Next.js 會將產生的用戶端套件和來源對應 .js.map 檔案，儲存在專案根目錄的 .next 目錄中。

React / Vite

如果 React 應用程式使用 Vite 做為建構套件組合器，請更新 vite.config.ts 檔案，在建構選項中發出來源對應：

// vite.config.ts
import { defineConfig } from 'vite';
import react from '@vitejs/plugin-react';

export default defineConfig({
  plugins: [react()],
  build: {
    // Emit sourcemap files for Crashlytics upload
    sourcemap: true,
  },
});

根據預設，Vite 會將產生的輸出套件和 .js.map 檔案儲存在 dist 目錄中。

步驟 2：使用 Firebase CLI 上傳來源對應

框架建構您的產品組合並產生 .js.map 檔案後，請使用 firebase crashlytics:sourcemap:upload 指令上傳來源對應：

firebase crashlytics:sourcemap:upload \
  --project PROJECT_ID \
  --app FIREBASE_APP_ID \
  --debug DIRECTORY

這個指令會遞迴搜尋指定 DIRECTORY 路徑 (dist 或 .next) 中的所有 .js.map 檔案，並上傳至 Cloud Storage 進行符號對應。

步驟 3：處理來源對應

如果生成來源對應時一併生成網頁應用程式素材資源，這些素材資源可能會公開給瀏覽器要求，導致原始原始碼外洩。如要避免這種情況，同時保留去模糊化的堆疊追蹤，您可以設定網路伺服器，拒絕公開存取 .js.map 檔案，或將 --clean 旗標傳遞至 firebase crashlytics:sourcemap:upload，以便在將 .js.map 檔案上傳至 Firebase 後，自動從本機建構目錄中刪除這些檔案。

在建構管道中自動執行

如要在部署前自動將來源對應上傳至 Crashlytics 並刪除本機 .js.map 檔案，請更新 package.json 檔案中的 build 指令碼，將 --clean 旗標傳遞至 firebase crashlytics:sourcemap:upload：

Angular

"scripts": {
  "build": "ng build && firebase crashlytics:sourcemap:upload --project PROJECT_ID --app FIREBASE_APP_ID --clean --debug dist"
}

Next.js

"scripts": {
  "build": "next build && firebase crashlytics:sourcemap:upload --project PROJECT_ID --app FIREBASE_APP_ID --clean --debug .next"
}

React / Vite

"scripts": {
  "build": "vite build && firebase crashlytics:sourcemap:upload --project PROJECT_ID --app FIREBASE_APP_ID --clean --debug dist"
}

後續步驟

  • 自訂當機報告：瞭解如何回報已處理的例外狀況、新增自訂鍵來搭配去模糊化的堆疊追蹤，以及設定取樣。