Google używa technologii AI do tłumaczenia treści na Twój preferowany język. Tłumaczenia wygenerowane przez AI mogą zawierać błędy.

Pierwsze kroki z Crashlytics w przypadku aplikacji internetowych

Wybierz platformę:

iOS+ Android Android NDK Web Flutter Unity

Z tego przewodnika dowiesz się, jak zacząć korzystać z Firebase Crashlytics w aplikacji internetowej.

Po skonfigurowaniu pakietu SDK Firebase Crashlytics w aplikacji możesz otrzymywać szczegółowe raporty o awariach w konsoli Firebase. Dzięki Crashlytics w przypadku aplikacji internetowych otrzymujesz raporty o błędach.

Zanim zaczniesz

Konfigurowanie Crashlytics wymaga wykonania zadań zarówno w konsoli Firebase, jak i w środowisku IDE (np. dodanie konfiguracji Firebase aplikacji i pakietu SDK Crashlytics). Aby dokończyć konfigurację, musisz wymusić testową awarię i wysłać pierwszy raport o awarii do Firebase.

Aby ręcznie skonfigurować Crashlytics w aplikacji internetowej, musisz spełnić te wymagania wstępne:

Jeśli nie masz jeszcze projektu w Firebase ani aplikacji w Firebase, utwórz je. Dodaj Firebase do projektu JavaScript, jeśli nie korzystasz w nim jeszcze z tej usługi.
Sprawdź, czy Twoje konto ma uprawnienia Właściciela w projekcie. Jest to wymagane do włączenia niezbędnych interfejsów API i ról uprawnień.
Upewnij się, że Twój projekt w Firebase jest objęty abonamentem Blaze z płatnością według wykorzystania. Crashlytics w przeglądarce używa Cloud Logging do przechowywania danych telemetrycznych i Cloud Storage do przechowywania map źródeł. Są to płatne usługi z bezpłatnym poziomem. Dowiedz się więcej o cenach Logging i cenach Cloud Storage.

Krok 1. Włącz Crashlytics w aplikacji internetowej

Crashlytics w internecie korzysta z Cloud Logging, Error Reporting i Cloud Storage, więc musisz włączyć te interfejsy API i skonfigurować uprawnienia w projekcie. Możesz włączyć Crashlytics w aplikacji internetowej za pomocą konsoli Firebase lub interfejsu wiersza poleceń Firebase.

Korzystanie z konsoli Firebase

W konsoli Firebase otwórz DevOps i zaangażowanie > panel Crashlytics.
Wybierz aplikację internetową w menu u góry strony.
Kliknij Skonfiguruj Crashlytics i postępuj zgodnie z instrukcjami wyświetlanymi na ekranie.

Korzystanie z interfejsu wiersza poleceń Firebase

Jeśli wolisz skonfigurować projekt z poziomu terminala lub za pomocą agenta kodowania AI, możesz użyć interfejsu wiersza poleceń Firebase:

Upewnij się, że masz zainstalowany interfejs wiersza poleceń Firebase w wersji 15.35.0 lub nowszej i że jesteś uwierzytelnionym użytkownikiem (firebase login). Dowiedz się, jak zainstalować lub zaktualizować interfejs wiersza poleceń Firebase.
Aby skonfigurować Crashlytics dla aplikacji internetowej, uruchom to polecenie:
```
firebase crashlytics:setup \
  --app FIREBASE_APP_ID \
  --project PROJECT_ID
```
To polecenie wykonuje następujące kroki konfiguracji:
- Sprawdza, czy projekt jest objęty abonamentem Blaze (płatność według wykorzystania), i w razie potrzeby wyświetla prośbę o przejście na wyższy abonament.
- Włącza wymagane interfejsy API Crashlytics i interfejsy telemetryczne (firebasetelemetry.googleapis.com, firebasetelemetryadmin.googleapis.com, firebasecrashlytics.googleapis.com i clienttelemetry.googleapis.com).
- Jeśli klucz interfejsu API aplikacji internetowej ma ograniczenia, dodaj clienttelemetry.googleapis.com do dozwolonych interfejsów API.
- Konfiguruje ustawienia telemetrii Crashlytics dla aplikacji internetowej.
- Gdy uruchomisz go interaktywnie, pojawi się prośba o opcjonalne włączenie alertów e-mail o nowych i powracających problemach.

Krok 2. Dodaj i zainicjuj pakiet SDK w aplikacji

Zainstaluj pakiet SDK Crashlytics:
```
npm install firebase
```

Zainicjuj instancję FirebaseApp:

Utwórz centralny plik narzędzia konfiguracji, aby używać inicjowania singletonu. Aby znaleźć wartości konfiguracji aplikacji w Firebase, otwórz stronę ustawienia projektu > Ogólne w konsoli Firebase, przejdź do karty Twoje aplikacje i wybierz aplikację internetową.

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

Krok 3. Skonfiguruj automatyczne przechwytywanie błędów dla swojej platformy

Zarówno automatyczne odbiorniki błędów platformy, jak i ręczne moduły śledzące korzystają z udostępnionej instancji FirebaseApp. Wybierz platformę, aby skonfigurować automatyczne przechwytywanie błędów:

Angular

Zintegruj z globalnym środowiskiem wykonawczym Angulara do przechwytywania błędów i automatycznym śledzeniem tras, dodając provideCrashlytics(() => app) do dostawców aplikacji w 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 lub nowszy (zalecany): instrumentacja klienta (instrumentation-client.ts)

Next.js 15.3 lub nowszy zawiera natywne instrumentowanie po stronie klienta za pomocą instrumentation-client.ts (lub instrumentation-client.js). Next.js wykonuje ten plik w przeglądarce, zanim rozpocznie się hydratacja React.

Utwórz plik src/instrumentation-client.ts (lub instrumentation-client.ts w katalogu głównym projektu, jeśli nie używasz katalogu src/) i zainicjuj Crashlytics:

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

getCrashlytics(app);

Ten pojedynczy plik inicjuje Crashlytics przed hydratacją Reacta i automatycznie rejestruje globalne detektory błędów (error i unhandledrejection) bez wprowadzania żadnych zmian w src/app/layout.tsx ani w żadnym komponencie Reacta.

Next.js < 15.3: po stronie klienta (układ App Router)

W przypadku wersji Next.js starszych niż 15.3 layout.tsx jest domyślnie komponentem serwera. Ponieważ FirebaseApp nie można serializować, opakuj <FirebaseCrashlytics> (z @firebase/crashlytics/react, aby zainicjować Crashlytics i przechwytywać nieobsługiwane błędy) w komponent klienta (np. src/components/CrashlyticsProvider.tsx) oznaczony dyrektywą '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}
    </>
  );
}

Następnie opakuj układ główny w <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 (bez React Router)

Opakuj komponent aplikacji głównej (zwykle src/App.tsx lub src/main.tsx) komponentem granicy błędu <FirebaseCrashlytics>. Działa jako globalny odbiornik, który obsługuje nieobsługiwane odrzucenia i wyjątki z przeglądarki i interfejsu React. Obejmuje wszystkie hierarchie komponentów podrzędnych i automatycznie przechwytuje nieobsługiwane wyjątki lub błędy routingu:

// 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 (wersja 6 lub nowsza)

Jeśli używasz React Router w wersji 6 lub nowszej, zastąp kontener <Routes> React Router kontenerem <CrashlyticsRoutes>. Dzięki temu granice błędów są automatycznie mapowane na trasach, a błędy są śledzone za pomocą nazw ścieżek szablonów, takich jak /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

Jeśli Twoja aplikacja używa TanStack Router, zainicjuj Crashlytics za pomocą getCrashlytics(app) i dołącz domyślne rejestrowanie błędów bezpośrednio w konfiguracji instancji routera (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);
  },
});

(Opcjonalnie) Krok 4. Skonfiguruj obsługę wersji aplikacji

Zdecydowanie zalecamy dodanie do kompilacji aplikacji internetowej czytelnego ciągu znaków wersji, aby można było wyizolować regresje do konkretnych wdrożeń. Podczas inicjowania pakietu SDK Crashlytics dla platformy przekaż appVersion w CrashlyticsOptions (używając ciągu wersji lub zmiennej środowiskowej czasu kompilacji, np. process.env.NEXT_PUBLIC_APP_VERSION lub import.meta.env.VITE_APP_VERSION):

Angular

Przekaż obiekt CrashlyticsOptions z wartością appVersion jako drugi argument do provideCrashlytics w 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 lub nowszy (zalecany): instrumentacja klienta (instrumentation-client.ts)

Przekaż obiekt CrashlyticsOptions z wartością appVersion jako drugi argument do getCrashlytics w 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: po stronie klienta (układ App Router)

Przekaż crashlyticsOptions z appVersion do <FirebaseCrashlytics> w 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 (bez React Router)

Przekaż crashlyticsOptions z appVersion do <FirebaseCrashlytics> w 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 (wersja 6 lub nowsza)

Przekaż crashlyticsOptions z appVersion do <CrashlyticsRoutes> w 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

Przekaż obiekt CrashlyticsOptions z wartością appVersion jako drugi argument do 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);
  },
});

Krok 5. Wymuś awarię testową

Aby dokończyć konfigurowanie usługi Crashlytics i zobaczyć początkowe dane w panelu Crashlytics w konsoli Firebase, musisz wymusić testową awarię.

Dodaj do aplikacji kod, którego możesz użyć do wymuszenia awarii testowej.

Dodaj do aplikacji React, Next.js lub Angular przycisk testowy lub aktywator trasy, który po kliknięciu wywołuje błąd środowiska wykonawczego:
```
// Trigger an unhandled exception on button click or route load
function handleTestCrash() {
  throw new Error("Crashlytics Web SDK Test Unhandled Error!");
}
```
Jeśli skonfigurowano automatyczne przechwytywanie błędów za pomocą <FirebaseCrashlytics> (React lub Next.js), provideCrashlytics (Angular) lub <CrashlyticsRoutes> (React Router), zgłoszenie tego błędu automatycznie przechwytuje wyjątek i planuje jego przesłanie.
Skompiluj i uruchom aplikację, a następnie wywołaj błąd testowy, aby aplikacja wysłała do Firebase pierwszy raport o awarii.
W konsoli Firebase otwórz panel DevOps & Engagement > Crashlytics, aby sprawdzić raport o awarii testowej:
1. Wybierz aplikację internetową w menu u góry strony.
2. Odśwież stronę. Testowy wyjątek powinien pojawić się w tabeli Problemy w ciągu kilku minut.

Jeśli po odświeżeniu konsoli i odczekaniu 5–10 minut nadal nie widzisz testowej awarii, zapoznaj się z sekcją Rozwiązywanie problemów z konfiguracją.

Crashlytics monitoruje teraz Twoją aplikację internetową pod kątem błędów. Otwórz panel Crashlytics, aby wyświetlić i przeanalizować wszystkie raporty i statystyki.

Dalsze kroki

Otrzymuj czytelne raporty o awariach: skonfiguruj automatyczne przesyłanie mapy źródła (.js.map), aby zrzuty stosu w środowisku produkcyjnym zawierały oryginalne nazwy plików i numery wierszy.
Dostosowywanie raportów o awariach: dowiedz się, jak zgłaszać obsługiwane wyjątki, dodawać klucze niestandardowe, wymuszać czyszczenie rekordów telemetrycznych i konfigurować próbkowanie.

Pierwsze kroki z Crashlytics w przypadku aplikacji internetowych Zadbaj o dobrą organizację dzięki kolekcji Zapisuj i kategoryzuj treści zgodnie ze swoimi preferencjami.

Zanim zaczniesz

Krok 1. Włącz Crashlytics w aplikacji internetowej

Korzystanie z konsoli Firebase

Korzystanie z interfejsu wiersza poleceń Firebase

Krok 2. Dodaj i zainicjuj pakiet SDK w aplikacji

Krok 3. Skonfiguruj automatyczne przechwytywanie błędów dla swojej platformy

Angular

Next.js

React (bez React Router)

React Router (wersja 6 lub nowsza)

TanStack Router

(Opcjonalnie) Krok 4. Skonfiguruj obsługę wersji aplikacji

Angular

Next.js

React (bez React Router)

React Router (wersja 6 lub nowsza)

TanStack Router

Krok 5. Wymuś awarię testową

Dalsze kroki

Pierwsze kroki z Crashlytics w przypadku aplikacji internetowych