| 选择平台: | iOS+ Android Android NDK Web Flutter Unity |
本指南介绍了如何在 Web 应用中开始使用 Firebase Crashlytics。
在应用中设置 Firebase Crashlytics SDK 后,您可以在 Firebase 控制台中获取全面的崩溃报告。通过 Crashlytics for Web 应用,您可以收到有关错误的报告。
AI 辅助功能的 AI 提示
如需 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,请确保您已满足以下前提条件:
如果您还没有 Firebase 项目和 Firebase 应用,请创建一个。如果您尚未将 Firebase 添加到您的 JavaScript 项目,请先添加。
确保您的账号对项目拥有所有者权限。这是启用必要的 API 和 IAM 角色所必需的。
确保您的 Firebase 项目采用的是随用随付 Blaze 定价方案。Crashlytics for Web 使用 Cloud Logging 存储遥测数据,使用 Cloud Storage 存储源映射,这些都是付费产品,但提供免费层级。详细了解 Logging 价格和 Cloud Storage 价格。
第 1 步:为您的 Web 应用启用 Crashlytics
Crashlytics for Web 使用 Cloud Logging、Error Reporting 和 Cloud Storage,因此您需要为项目启用这些 API 并配置权限。您可以使用 Firebase 控制台或 Firebase CLI 为 Web 应用启用 Crashlytics。
使用 Firebase 控制台
在 Firebase 控制台中,前往 DevOps 和互动 > Crashlytics 信息中心。
从页面顶部的下拉选择器中选择您的 Web 应用。
点击设置 Crashlytics,然后按照屏幕上的说明操作。
使用 Firebase CLI
如果您更喜欢通过终端配置项目或使用 AI 编码代理,可以使用 Firebase CLI:
确保您已安装 Firebase CLI v15.35.0 或更高版本,并且已通过身份验证 (
firebase login)。了解如何安装或更新 Firebase CLI。运行以下命令,为您的 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
安装 Crashlytics SDK:
npm install firebase初始化
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 信息中心内查看初始数据,您需要强制造成一次测试崩溃。
向应用添加可用于强制造成测试崩溃的代码。
向 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) 配置了自动错误捕获,则抛出此错误会自动捕获异常并安排上传。构建并运行您的应用,然后触发测试错误,以便您的应用向 Firebase 发送其第一个崩溃报告。
在 Firebase 控制台中,前往 DevOps 和互动 > Crashlytics 信息中心,查看您的测试崩溃报告:
从页面顶部的下拉选择器中选择您的 Web 应用。
刷新页面。您的测试异常应该会在几分钟内显示在问题表中。
如果您已刷新控制台,但在 5 到 10 分钟后仍未看到测试崩溃报告,请参阅设置问题排查。
Crashlytics 现在会监控您的 Web 应用是否发生错误。您可以访问 Crashlytics 信息中心,查看和分析所有报告及统计信息。
后续步骤
- 获取可读的崩溃报告:设置自动上传源代码映射 (
.js.map),以便生产堆栈轨迹显示原始文件名和行号。 - 自定义崩溃报告:了解如何报告已处理的异常、添加自定义键、强制刷新遥测记录以及配置采样。
- 通过 MCP 借助 AI 辅助进行调试:使用 Crashlytics MCP 工具和
crashlytics:connect工作流,通过 AI 编码智能体确定 Web 问题的优先级、调查并修复这些问题。