Google 会使用 AI 技术将内容翻译成您偏好的语言。AI 翻译可能包含错误。

Crashlytics Web 版使用入门

选择平台：

iOS+ Android Android NDK Web Flutter Unity

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

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

准备工作

设置 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）

使用 <FirebaseCrashlytics> 错误边界组件封装根应用组件（通常为 src/App.tsx 或 src/main.tsx）。这会充当全局接收器，处理来自浏览器和 React 界面的未处理拒绝和异常。它会封装所有子组件层次结构，并自动捕获未捕获的异常或路由错误：

// 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({
  children,
}: {
  children?: React.ReactNode;
}) {
  return (
    <FirebaseCrashlytics firebaseApp={app}>
      {children}
    </FirebaseCrashlytics>
  );
}

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

将 CrashlyticsOptions 对象（appVersion 作为第二个参数）传递给 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)

将 CrashlyticsOptions 对象（appVersion 作为第二个参数）传递给 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({
  children,
}: {
  children?: React.ReactNode;
}) {
  return (
    <FirebaseCrashlytics
      firebaseApp={app}
      crashlyticsOptions={crashlyticsOptions}
    >
      {children}
    </FirebaseCrashlytics>
  );
}

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 信息中心，查看您的测试崩溃报告：
1. 从页面顶部的下拉选择器中选择您的 Web 应用。
2. 刷新页面。您的测试异常应该会在几分钟内显示在问题表中。

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

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

后续步骤

获取可读的崩溃报告：设置自动上传源代码映射 (.js.map)，以便生产堆栈轨迹显示原始文件名和行号。
自定义崩溃报告：了解如何报告已处理的异常、添加自定义键、强制刷新遥测记录以及配置采样。

Crashlytics Web 版使用入门 使用集合让一切井井有条 根据您的偏好保存内容并对其进行分类。

准备工作

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

使用 Firebase 控制台

使用 Firebase CLI

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

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

Angular

Next.js

React（不含 React Router）

React Router (v6+)

TanStack Router

（可选）第 4 步：设置应用版本控制

Angular

Next.js

React（不含 React Router）

React Router (v6+)

TanStack Router

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

后续步骤

Crashlytics Web 版使用入门