Google sử dụng công nghệ AI để dịch nội dung sang ngôn ngữ bạn ưu tiên. Bản dịch bằng AI có thể có lỗi.

Bắt đầu sử dụng Crashlytics cho web

Chọn nền tảng:

iOS+ Android Android NDK Web Flutter Unity

Hướng dẫn này mô tả cách bắt đầu sử dụng Firebase Crashlytics trong ứng dụng web của bạn.

Sau khi thiết lập SDK Firebase Crashlytics trong ứng dụng, bạn có thể nhận được báo cáo sự cố toàn diện trong bảng điều khiển Firebase. Với Crashlytics cho ứng dụng web, bạn sẽ nhận được báo cáo về lỗi.

Trước khi bắt đầu

Để thiết lập Crashlytics, bạn cần thực hiện các thao tác trong cả bảng điều khiển Firebase và IDE (chẳng hạn như thêm cấu hình Firebase của ứng dụng và SDK Crashlytics). Để hoàn tất việc thiết lập, bạn cần xác định sự cố thử nghiệm để gửi báo cáo sự cố đầu tiên đến Firebase.

Để thiết lập Crashlytics theo cách thủ công trong ứng dụng web, hãy đảm bảo bạn đã hoàn tất các điều kiện tiên quyết sau:

Tạo dự án Firebase và ứng dụng Firebase nếu bạn chưa có. Nếu bạn chưa thực hiện, hãy thêm Firebase vào dự án JavaScript.
Đảm bảo rằng tài khoản của bạn có quyền Chủ sở hữu đối với dự án. Bạn cần có quyền này để bật các API và vai trò IAM cần thiết.
Đảm bảo dự án Firebase của bạn đang sử dụng gói giá Blaze (trả tiền theo mức dùng). Crashlytics cho web sử dụng Cloud Logging để lưu trữ dữ liệu đo từ xa và Cloud Storage để lưu trữ bản đồ nguồn. Đây là các sản phẩm có tính phí và có cấp không tốn phí. Tìm hiểu thêm về giá của Logging và giá của Cloud Storage.

Bước 1: Bật Crashlytics cho ứng dụng web của bạn

Crashlytics cho web sử dụng Cloud Logging, Error Reporting và Cloud Storage, vì vậy, bạn cần bật các API này và định cấu hình quyền cho dự án của mình. Bạn có thể bật Crashlytics cho ứng dụng web của mình bằng bảng điều khiển Firebase hoặc CLI Firebase.

Sử dụng bảng điều khiển Firebase

Trong bảng điều khiển Firebase, hãy chuyển đến DevOps & Engagement (DevOps và Mức độ tương tác) > trang tổng quan Crashlytics.
Chọn ứng dụng web của bạn trong bộ chọn thả xuống ở đầu trang.
Nhấp vào Thiết lập Crashlytics rồi làm theo hướng dẫn trên màn hình.

Sử dụng CLI Firebase

Nếu muốn định cấu hình dự án từ thiết bị đầu cuối hoặc sử dụng tác nhân lập trình AI, bạn có thể dùng CLI Firebase:

Đảm bảo rằng bạn đã cài đặt Firebase CLI phiên bản 15.35.0 trở lên và đã xác thực (firebase login). Tìm hiểu cách cài đặt hoặc cập nhật Firebase CLI.
Chạy lệnh sau để thiết lập Crashlytics cho ứng dụng web của bạn:
```
firebase crashlytics:setup \
  --app FIREBASE_APP_ID \
  --project PROJECT_ID
```
Lệnh này thực hiện các bước thiết lập sau:
- Xác minh rằng dự án của bạn đang sử dụng gói giá Blaze (trả tiền theo mức dùng) và nhắc bạn nâng cấp nếu cần.
- Bật các API đo từ xa và Crashlytics bắt buộc (firebasetelemetry.googleapis.com, firebasetelemetryadmin.googleapis.com, firebasecrashlytics.googleapis.com và clienttelemetry.googleapis.com).
- Nếu khoá API của ứng dụng web có các quy tắc hạn chế về API, hãy thêm clienttelemetry.googleapis.com vào các API được phép.
- Định cấu hình chế độ cài đặt dữ liệu đo từ xa Crashlytics cho ứng dụng web của bạn.
- Khi chạy theo cách tương tác, công cụ này sẽ nhắc bạn bật cảnh báo qua email (không bắt buộc) cho các vấn đề mới và vấn đề tái diễn.

Bước 2: Thêm và khởi chạy SDK trong ứng dụng

Cài đặt SDK Crashlytics:
```
npm install firebase
```

Khởi động thực thể FirebaseApp:

Tạo một tệp tiện ích cấu hình trung tâm để sử dụng phương thức khởi chạy singleton. Để tìm các giá trị cấu hình ứng dụng Firebase, hãy chuyển đến trang Cài đặt dự án > Chung trong bảng điều khiển Firebase, chuyển đến thẻ Ứng dụng của bạn rồi chọn ứng dụng web của bạn.

// 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();

Bước 3: Định cấu hình tính năng tự động ghi lại lỗi cho khung của bạn

Cả trình nhận lỗi khung tự động và trình theo dõi thủ công đều sử dụng thực thể FirebaseApp dùng chung của bạn. Chọn khung để định cấu hình tính năng tự động ghi lại lỗi:

Angular

Tích hợp với thời gian chạy bắt lỗi chung của Angular và tính năng theo dõi tuyến đường tự động bằng cách thêm provideCrashlytics(() => app) vào nhà cung cấp của ứng dụng trong src/app/app.config.ts:

// 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 trở lên (nên dùng): Thiết bị đo lường ứng dụng (instrumentation-client.ts)

Next.js 15.3 trở lên có khả năng đo lường phía máy khách gốc thông qua instrumentation-client.ts (hoặc instrumentation-client.js). Next.js thực thi tệp này trong trình duyệt trước khi quá trình hydrat hoá React bắt đầu.

Tạo src/instrumentation-client.ts (hoặc instrumentation-client.ts trong thư mục gốc của dự án nếu không sử dụng thư mục src/) và khởi chạy Crashlytics:

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

getCrashlytics(app);

Tệp duy nhất này khởi chạy Crashlytics trước khi React hydrat hoá và tự động đăng ký trình nghe lỗi chung (error và unhandledrejection) mà không cần sửa đổi src/app/layout.tsx hoặc bất kỳ thành phần React nào.

Next.js < 15.3: Phía máy khách (bố cục Bộ định tuyến ứng dụng)

Đối với các phiên bản Next.js cũ hơn 15.3, layout.tsx là một Thành phần máy chủ theo mặc định. Vì FirebaseApp không thể chuyển đổi tuần tự, hãy gói <FirebaseCrashlytics> (từ @firebase/crashlytics/react để khởi chạy Crashlytics và ghi lại các lỗi chưa được phát hiện) trong một Thành phần ứng dụng (chẳng hạn như src/components/CrashlyticsProvider.tsx) được đánh dấu bằng lệnh 'use client':

// 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}
    </>
  );
}

Sau đó, gói bố cục gốc bằng <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 (không có React Router)

Gói thành phần ứng dụng gốc (thường là src/App.tsx hoặc src/main.tsx) bằng thành phần ranh giới lỗi <FirebaseCrashlytics>. Thành phần này đóng vai trò là trình nhận chung, xử lý các trường hợp từ chối và ngoại lệ chưa được xử lý từ trình duyệt và giao diện người dùng React. Thành phần này bao bọc tất cả hệ phân cấp thành phần con và tự động ghi lại các ngoại lệ chưa được phát hiện hoặc lỗi định tuyến:

// 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 (phiên bản 6 trở lên)

Nếu bạn đang sử dụng React Router phiên bản 6 trở lên, hãy thay thế vùng chứa <Routes> của React Router bằng <CrashlyticsRoutes>. Thao tác này sẽ tự động liên kết ranh giới lỗi trên các tuyến đường và theo dõi lỗi bằng tên đường dẫn theo mẫu, chẳng hạn như /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

Nếu ứng dụng của bạn sử dụng TanStack Router, hãy khởi động Crashlytics bằng getCrashlytics(app) và đính kèm bản ghi lỗi mặc định ngay trong cấu hình thực thể bộ định tuyến (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);
  },
});

(Không bắt buộc) Bước 4: Thiết lập tính năng tạo phiên bản ứng dụng

Bạn nên thêm một chuỗi phiên bản rõ ràng vào các bản dựng ứng dụng web để có thể tách riêng các bản hồi quy cho những lần triển khai cụ thể. Truyền appVersion vào CrashlyticsOptions khi khởi chạy SDK Crashlytics cho khung của bạn (bằng cách sử dụng chuỗi phát hành hoặc biến môi trường thời gian xây dựng, chẳng hạn như process.env.NEXT_PUBLIC_APP_VERSION hoặc import.meta.env.VITE_APP_VERSION):

Angular

Truyền một đối tượng CrashlyticsOptions có appVersion làm đối số thứ hai vào provideCrashlytics trong src/app/app.config.ts:

// 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 trở lên (nên dùng): Thiết bị đo lường ứng dụng (instrumentation-client.ts)

Truyền một đối tượng CrashlyticsOptions có appVersion làm đối số thứ hai vào getCrashlytics trong src/instrumentation-client.ts:

// 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: Phía máy khách (bố cục Bộ định tuyến ứng dụng)

Truyền crashlyticsOptions bằng appVersion đến <FirebaseCrashlytics> trong 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

const crashlyticsOptions = {
  appVersion: 'APP_VERSION'
};

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

React (không có React Router)

Truyền crashlyticsOptions bằng appVersion đến <FirebaseCrashlytics> trong src/App.tsx:

// 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 (phiên bản 6 trở lên)

Truyền crashlyticsOptions bằng appVersion đến <CrashlyticsRoutes> trong src/App.tsx:

// 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

Truyền một đối tượng CrashlyticsOptions có appVersion làm đối số thứ hai vào 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);
  },
});

Bước 5: Buộc xảy ra sự cố thử nghiệm

Để hoàn tất việc thiết lập Crashlytics và xem dữ liệu ban đầu trên trang tổng quan Crashlytics trong bảng điều khiển của Firebase, bạn cần xác định sự cố thử nghiệm.

Thêm mã vào ứng dụng để bạn có thể dùng mã đó nhằm buộc xảy ra sự cố thử nghiệm.

Thêm nút kiểm thử hoặc trình kích hoạt định tuyến vào ứng dụng React, Next.js hoặc Angular của bạn để gửi lỗi thời gian chạy khi người dùng nhấp vào:
```
// Trigger an unhandled exception on button click or route load
function handleTestCrash() {
  throw new Error("Crashlytics Web SDK Test Unhandled Error!");
}
```
Nếu bạn đã định cấu hình tính năng tự động ghi lại lỗi bằng <FirebaseCrashlytics> (React hoặc Next.js), provideCrashlytics (Angular) hoặc <CrashlyticsRoutes> (React Router), thì việc gửi lỗi này sẽ tự động ghi lại ngoại lệ và lên lịch tải ngoại lệ đó lên.
Tạo và chạy ứng dụng, sau đó kích hoạt lỗi kiểm thử để ứng dụng gửi báo cáo sự cố đầu tiên đến Firebase.
Trong bảng điều khiển Firebase, hãy chuyển đến trang tổng quan DevOps & Engagement (DevOps và Mức độ tương tác) > Crashlytics để kiểm tra báo cáo sự cố thử nghiệm:
1. Chọn ứng dụng web của bạn trong bộ chọn thả xuống ở đầu trang.
2. Làm mới trang. Trường hợp ngoại lệ kiểm thử của bạn sẽ xuất hiện trong bảng Vấn đề trong vòng vài phút.

Nếu bạn đã làm mới bảng điều khiển mà vẫn không thấy sự cố kiểm thử sau 5 đến 10 phút, hãy xem phần Khắc phục sự cố khi thiết lập.

Crashlytics hiện đang theo dõi ứng dụng web của bạn để tìm lỗi. Truy cập vào trang tổng quan Crashlytics để xem và tìm hiểu tất cả báo cáo và số liệu thống kê của bạn.

Các bước tiếp theo

Nhận báo cáo sự cố dễ đọc: Thiết lập tính năng tự động tải bản đồ nguồn (.js.map) lên để dấu vết ngăn xếp trong môi trường phát hành công khai hiển thị tên tệp và số dòng ban đầu.
Tuỳ chỉnh báo cáo sự cố: Tìm hiểu cách báo cáo các ngoại lệ đã xử lý, thêm khoá tuỳ chỉnh, buộc xoá bản ghi đo từ xa và định cấu hình lấy mẫu.

Bắt đầu sử dụng Crashlytics cho web Sử dụng bộ sưu tập để sắp xếp ngăn nắp các trang Lưu và phân loại nội dung dựa trên lựa chọn ưu tiên của bạn.

Trước khi bắt đầu

Bước 1: Bật Crashlytics cho ứng dụng web của bạn

Sử dụng bảng điều khiển Firebase

Sử dụng CLI Firebase

Bước 2: Thêm và khởi chạy SDK trong ứng dụng

Bước 3: Định cấu hình tính năng tự động ghi lại lỗi cho khung của bạn

Angular

Next.js

React (không có React Router)

React Router (phiên bản 6 trở lên)

TanStack Router

(Không bắt buộc) Bước 4: Thiết lập tính năng tạo phiên bản ứng dụng

Angular

Next.js

React (không có React Router)

React Router (phiên bản 6 trở lên)

TanStack Router

Bước 5: Buộc xảy ra sự cố thử nghiệm

Các bước tiếp theo

Bắt đầu sử dụng Crashlytics cho web