Crashlytics Web 版使用入门

选择平台: iOS+ Android Android NDK Web Flutter Unity


本指南介绍了如何在 Web 应用中开始使用 Firebase Crashlytics。

在应用中设置 Firebase Crashlytics SDK 后,您可以在 Firebase 控制台中获取全面的崩溃报告。通过 Crashlytics for Web 应用,您可以收到有关错误的报告。

如需 AI 辅助,请将以下提示复制到您的 AI 编码智能体(例如 Antigravity、Claude Code、Codex 和 Cursor)中。 您可以自定义提示,并与代理进行迭代。如需了解详细的安装信息,请访问 Firebase 智能体技能。

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 发送您的第一个崩溃报告。

如需在 Web 应用中手动设置 Crashlytics,请确保您已满足以下前提条件:

第 1 步:为您的 Web 应用启用 Crashlytics

Crashlytics for Web 使用 Cloud Logging、Error Reporting 和 Cloud Storage,因此您需要为项目启用这些 API 并配置权限。您可以使用 Firebase 控制台或 Firebase CLI 为 Web 应用启用 Crashlytics。

使用 Firebase 控制台

  1. 在 Firebase 控制台中,前往 DevOps 和互动 > Crashlytics 信息中心。

  2. 从页面顶部的下拉选择器中选择您的 Web 应用。

  3. 点击设置 Crashlytics,然后按照屏幕上的说明操作。

使用 Firebase CLI

如果您更喜欢通过终端配置项目或使用 AI 编码代理,可以使用 Firebase CLI:

  1. 确保您已安装 Firebase CLI v15.35.0 或更高版本,并且已通过身份验证 (firebase login)。了解如何安装或更新 Firebase CLI。

  2. 运行以下命令,为您的 Web 应用设置 Crashlytics:

    firebase crashlytics:setup \
      --app FIREBASE_APP_ID \
      --project PROJECT_ID
    

    此命令会执行以下设置步骤:

    • 验证您的项目是否采用随用随付 Blaze 定价方案,并根据需要提示您升级。

    • 启用所需的 Crashlytics 和遥测 API(firebasetelemetry.googleapis.com、firebasetelemetryadmin.googleapis.com、firebasecrashlytics.googleapis.com 和 clienttelemetry.googleapis.com)。

    • 如果 Web 应用的 API 密钥具有 API 限制,请将 clienttelemetry.googleapis.com 添加到其允许的 API 中。

    • 为您的 Web 应用配置 Crashlytics 遥测设置。

    • 以交互方式运行时,系统会提示您选择是否为新问题和回归问题启用邮件提醒。

第 2 步:在应用中添加并初始化 SDK

  1. 安装 Crashlytics SDK:

    npm install firebase
    
  2. 初始化 FirebaseApp 实例:

    创建中央配置实用程序文件,以使用单例初始化。 如需查找 Firebase 应用配置值,请在 Firebase 控制台中前往 项目设置 > 常规页面,然后前往您的应用卡片,并选择您的 Web 应用。

    // src/lib/firebase.ts
    import { initializeApp, getApps, getApp } from '@firebase/app';
    
    const firebaseConfig = {
      apiKey: "API_KEY",
      authDomain: "AUTH_DOMAIN",
      projectId: "PROJECT_ID",
      storageBucket: "STORAGE_BUCKET",
      messagingSenderId: "MESSAGING_SENDER_ID",
      appId: "FIREBASE_APP_ID"
    };
    
    // Guarantee singleton initialization across renders or module refreshes
    export const app = getApps().length === 0
      ? initializeApp(firebaseConfig)
      : getApp();
    

第 3 步:为框架配置自动错误捕获

自动框架错误接收器和手动跟踪器都使用共享的 FirebaseApp 实例。选择您的框架以配置自动错误捕获:

Angular

通过在 src/app/app.config.ts 中将 provideCrashlytics(() => app) 添加到应用的提供程序,与 Angular 全局错误捕获运行时和自动路由跟踪集成:

// src/app/app.config.ts
import { ApplicationConfig } from '@angular/core';
import { provideRouter } from '@angular/router';
import { provideCrashlytics } from '@firebase/crashlytics/angular';
import { app } from '../lib/firebase'; // Shared initialization script
import { routes } from './app.routes';

export const appConfig: ApplicationConfig = {
  providers: [
    provideRouter(routes),
    provideCrashlytics(() => app)
  ]
};

Next.js

Next.js 15.3+(推荐):客户端插桩 (instrumentation-client.ts)

Next.js 15.3+ 通过 instrumentation-client.ts(或 instrumentation-client.js)包含原生客户端插桩。Next.js 会在 React 水合开始之前在浏览器中执行此文件。

创建 src/instrumentation-client.ts(如果不使用 src/ 目录,则在项目根目录中创建 instrumentation-client.ts)并初始化 Crashlytics:

// src/instrumentation-client.ts
import { getCrashlytics } from '@firebase/crashlytics';
import { app } from './lib/firebase'; // Shared initialization script

getCrashlytics(app);

这个单一文件会在 React 水合之前初始化 Crashlytics,并自动注册全局错误监听器(error 和 unhandledrejection),而无需对 src/app/layout.tsx 或任何 React 组件进行任何修改。

Next.js < 15.3:客户端(应用路由器布局)

对于 15.3 之前的 Next.js 版本,layout.tsx 默认是服务器组件。由于 FirebaseApp 不可序列化,因此请将 <FirebaseCrashlytics>(来自 @firebase/crashlytics/react,用于初始化 Crashlytics 并捕获未捕获的错误)封装在标有 'use client' 指令的客户端组件(例如 src/components/CrashlyticsProvider.tsx)中:

// src/components/CrashlyticsProvider.tsx
'use client';

import React from 'react';
import { FirebaseCrashlytics } from '@firebase/crashlytics/react';
import { app } from '../lib/firebase'; // Shared initialization script

export function CrashlyticsProvider({
  children,
}: {
  children: React.ReactNode;
}) {
  return (
    <>
      <FirebaseCrashlytics firebaseApp={app} />
      {children}
    </>
  );
}

然后,使用 <CrashlyticsProvider> 封装根布局:

// src/app/layout.tsx
import React from 'react';
import { CrashlyticsProvider } from '../components/CrashlyticsProvider';

export default function RootLayout({
  children,
}: {
  children: React.ReactNode;
}) {
  return (
    <html lang="en">
      <body>
        <CrashlyticsProvider>
          {children}
        </CrashlyticsProvider>
      </body>
    </html>
  );
}

React(不含 React Router)

在应用根目录附近(例如在 src/App.tsx 或 src/main.tsx 中)与其他组件一起呈现 <FirebaseCrashlytics>。它会初始化 Crashlytics 并监听未捕获的错误和未处理的 promise 拒绝:

// src/App.tsx
import React from 'react';
import { FirebaseCrashlytics } from '@firebase/crashlytics/react';
import { app } from './lib/firebase'; // Shared initialization script

export default function App() {
  return (
    <>
      <FirebaseCrashlytics firebaseApp={app} />
      {/* Your app components */}
    </>
  );
}

React Router (v6+)

如果您使用的是 React Router v6+,请将 React Router 的 <Routes> 容器替换为 <CrashlyticsRoutes>。这会自动跨路由映射错误边界,并使用模板化路径名称(例如 /profile/:userId)跟踪错误:

// src/App.tsx
import React from 'react';
import { BrowserRouter, Route } from 'react-router-dom';
import { CrashlyticsRoutes } from '@firebase/crashlytics/react-router';
import { app } from './lib/firebase'; // Shared initialization script
import Home from './pages/Home';
import Profile from './pages/Profile';
import Product from './pages/Product';

export default function App() {
  return (
    <BrowserRouter>
      <CrashlyticsRoutes firebaseApp={app}>
        <Route path="/" element={<Home />} />
        <Route path="/profile/:userId" element={<Profile />} />
        <Route path="/product/:productId/details" element={<Product />} />
      </CrashlyticsRoutes>
    </BrowserRouter>
  );
}

TanStack Router

如果您的应用使用 TanStack Router,请使用 getCrashlytics(app) 初始化 Crashlytics,并直接在路由器实例配置 (defaultOnCatch) 中附加默认错误记录:

import { recordError, getCrashlytics } from '@firebase/crashlytics';
import { app } from './lib/firebase'; // Shared initialization script

import { createRouter } from '@tanstack/react-router';
import { routeTree } from './routeTree.gen';

const crashlytics = getCrashlytics(app);

const router = createRouter({
  routeTree,
  defaultOnCatch: (error, errorInfo) => {
    recordError(crashlytics, error, errorInfo);
  },
});

(可选)第 4 步:设置应用版本控制

强烈建议您为 Web 应用 build 添加清晰的版本字符串,以便将回归问题隔离到特定部署。在为框架初始化 Crashlytics SDK 时,在 CrashlyticsOptions 中传递 appVersion(使用发布字符串或 build 时环境变量,例如 process.env.NEXT_PUBLIC_APP_VERSION 或 import.meta.env.VITE_APP_VERSION):

Angular

将包含 appVersion 的 CrashlyticsOptions 对象作为第二个参数传递给 src/app/app.config.ts 中的 provideCrashlytics:

// src/app/app.config.ts
import { ApplicationConfig } from '@angular/core';
import { provideRouter } from '@angular/router';
import { provideCrashlytics } from '@firebase/crashlytics/angular';
import { app } from '../lib/firebase'; // Shared initialization script
import { routes } from './app.routes';

export const appConfig: ApplicationConfig = {
  providers: [
    provideRouter(routes),
    provideCrashlytics(() => app, {
      appVersion: 'APP_VERSION'
    })
  ]
};

Next.js

Next.js 15.3+(推荐):客户端插桩 (instrumentation-client.ts)

将包含 appVersion 的 CrashlyticsOptions 对象作为第二个参数传递给 src/instrumentation-client.ts 中的 getCrashlytics:

// src/instrumentation-client.ts
import { getCrashlytics } from '@firebase/crashlytics';
import { app } from './lib/firebase'; // Shared initialization script

getCrashlytics(app, {
  appVersion: 'APP_VERSION'
});

Next.js < 15.3:客户端(应用路由器布局)

在 src/components/CrashlyticsProvider.tsx 中将带有 appVersion 的 crashlyticsOptions 传递给 <FirebaseCrashlytics>:

// src/components/CrashlyticsProvider.tsx
'use client';

import React from 'react';
import { FirebaseCrashlytics } from '@firebase/crashlytics/react';
import { app } from '../lib/firebase'; // Shared initialization script

const crashlyticsOptions = {
  appVersion: 'APP_VERSION'
};

export function CrashlyticsProvider({
  children,
}: {
  children: React.ReactNode;
}) {
  return (
    <>
      <FirebaseCrashlytics
        firebaseApp={app}
        crashlyticsOptions={crashlyticsOptions}
      />
      {children}
    </>
  );
}

React(不含 React Router)

在 src/App.tsx 中将带有 appVersion 的 crashlyticsOptions 传递给 <FirebaseCrashlytics>:

// src/App.tsx
import React from 'react';
import { FirebaseCrashlytics } from '@firebase/crashlytics/react';
import { app } from './lib/firebase'; // Shared initialization script

const crashlyticsOptions = {
  appVersion: 'APP_VERSION'
};

export default function App() {
  return (
    <>
      <FirebaseCrashlytics
        firebaseApp={app}
        crashlyticsOptions={crashlyticsOptions}
      />
      {/* Your app components */}
    </>
  );
}

React Router (v6+)

在 src/App.tsx 中将带有 appVersion 的 crashlyticsOptions 传递给 <CrashlyticsRoutes>:

// src/App.tsx
import React from 'react';
import { BrowserRouter, Route } from 'react-router-dom';
import { CrashlyticsRoutes } from '@firebase/crashlytics/react-router';
import { app } from './lib/firebase'; // Shared initialization script
import Home from './pages/Home';
import Profile from './pages/Profile';
import Product from './pages/Product';

const crashlyticsOptions = {
  appVersion: 'APP_VERSION'
};

export default function App() {
  return (
    <BrowserRouter>
      <CrashlyticsRoutes
        firebaseApp={app}
        crashlyticsOptions={crashlyticsOptions}
      >
        <Route path="/" element={<Home />} />
        <Route path="/profile/:userId" element={<Profile />} />
        <Route path="/product/:productId/details" element={<Product />} />
      </CrashlyticsRoutes>
    </BrowserRouter>
  );
}

TanStack Router

将包含 appVersion 的 CrashlyticsOptions 对象作为第二个参数传递给 getCrashlytics:

import { recordError, getCrashlytics } from '@firebase/crashlytics';
import { app } from './lib/firebase'; // Shared initialization script

import { createRouter } from '@tanstack/react-router';
import { routeTree } from './routeTree.gen';

const crashlytics = getCrashlytics(app, {
  appVersion: 'APP_VERSION'
});

const router = createRouter({
  routeTree,
  defaultOnCatch: (error, errorInfo) => {
    recordError(crashlytics, error, errorInfo);
  },
});

第 5 步:强制造成一次测试崩溃

如需完成 Crashlytics 设置并在 Firebase 控制台的 Crashlytics 信息中心内查看初始数据,您需要强制造成一次测试崩溃。

  1. 向应用添加可用于强制造成测试崩溃的代码。

    向 React、Next.js 或 Angular 应用添加一个测试按钮或路由触发器,以便在点击时抛出运行时错误:

    // Trigger an unhandled exception on button click or route load
    function handleTestCrash() {
      throw new Error("Crashlytics Web SDK Test Unhandled Error!");
    }
    

    如果您使用 <FirebaseCrashlytics>(React 或 Next.js)、provideCrashlytics (Angular) 或 <CrashlyticsRoutes> (React Router) 配置了自动错误捕获,则抛出此错误会自动捕获异常并安排上传。

  2. 构建并运行您的应用,然后触发测试错误,以便您的应用向 Firebase 发送其第一个崩溃报告。

  3. 在 Firebase 控制台中,前往 DevOps 和互动 > Crashlytics 信息中心,查看您的测试崩溃报告:

    1. 从页面顶部的下拉选择器中选择您的 Web 应用。

    2. 刷新页面。您的测试异常应该会在几分钟内显示在问题表中。

如果您已刷新控制台,但在 5 到 10 分钟后仍未看到测试崩溃报告,请参阅设置问题排查。


Crashlytics 现在会监控您的 Web 应用是否发生错误。您可以访问 Crashlytics 信息中心,查看和分析所有报告及统计信息。

后续步骤

  • 获取可读的崩溃报告:设置自动上传源代码映射 (.js.map),以便生产堆栈轨迹显示原始文件名和行号。
  • 自定义崩溃报告:了解如何报告已处理的异常、添加自定义键、强制刷新遥测记录以及配置采样。
  • 通过 MCP 借助 AI 辅助进行调试:使用 Crashlytics MCP 工具和 crashlytics:connect 工作流,通过 AI 编码智能体确定 Web 问题的优先级、调查并修复这些问题。