14 września 2025Polski

Kompleksowy przewodnik po zrozumieniu i implementacji JavaScript Error Boundaries w React dla solidnej obsługi błędów i płynnej degradacji interfejsu.

JavaScript Error Boundary: Przewodnik po implementacji obsługi błędów w React

W świecie programowania w React, nieoczekiwane błędy mogą prowadzić do frustrujących doświadczeń użytkownika i niestabilności aplikacji. Dobrze zdefiniowana strategia obsługi błędów jest kluczowa dla budowania solidnych i niezawodnych aplikacji. Error Boundaries w React dostarczają potężnego mechanizmu do płynnej obsługi błędów występujących w drzewie komponentów, zapobiegając awarii całej aplikacji i pozwalając na wyświetlenie zapasowego interfejsu użytkownika (fallback UI).

Czym jest Error Boundary?

Error Boundary to komponent React, który przechwytuje błędy JavaScript w dowolnym miejscu w swoim drzewie komponentów potomnych, loguje te błędy i wyświetla zapasowy interfejs użytkownika zamiast drzewa komponentów, które uległo awarii. Error Boundaries przechwytują błędy podczas renderowania, w metodach cyklu życia oraz w konstruktorach całego drzewa znajdującego się poniżej nich.

Można myśleć o Error Boundary jak o bloku try...catch dla komponentów React. Tak jak blok try...catch pozwala na obsługę wyjątków w synchronicznym kodzie JavaScript, tak Error Boundary pozwala na obsługę błędów występujących podczas renderowania komponentów React.

Ważna uwaga: Error Boundaries nie przechwytują błędów dla:

Procedur obsługi zdarzeń (dowiedz się więcej w kolejnych sekcjach)
Kodu asynchronicznego (np. wywołania zwrotne setTimeout lub requestAnimationFrame)
Renderowania po stronie serwera
Błędów zgłaszanych w samym komponencie Error Boundary (a nie w jego dzieciach)

Dlaczego warto używać Error Boundaries?

Używanie Error Boundaries oferuje kilka znaczących korzyści:

Lepsze doświadczenie użytkownika: Zamiast wyświetlać pusty, biały ekran lub zagadkowy komunikat o błędzie, można pokazać przyjazny dla użytkownika zapasowy interfejs, informując go, że coś poszło nie tak i potencjalnie oferując sposób na odzyskanie (np. przeładowanie strony lub przejście do innej sekcji).
Stabilność aplikacji: Error Boundaries zapobiegają awarii całej aplikacji z powodu błędów w jednej jej części. Jest to szczególnie ważne w przypadku złożonych aplikacji z wieloma połączonymi komponentami.
Scentralizowana obsługa błędów: Error Boundaries zapewniają scentralizowane miejsce do logowania błędów i śledzenia ich pierwotnej przyczyny. Upraszcza to debugowanie i konserwację.
Płynna degradacja: Można strategicznie umieszczać Error Boundaries wokół różnych części aplikacji, aby zapewnić, że nawet jeśli niektóre komponenty zawiodą, reszta aplikacji pozostanie funkcjonalna. Pozwala to na płynną degradację w obliczu błędów.

Implementacja Error Boundaries w React

Aby stworzyć Error Boundary, należy zdefiniować komponent klasowy, który implementuje jedną (lub obie) z następujących metod cyklu życia:

static getDerivedStateFromError(error): Ta metoda cyklu życia jest wywoływana po zgłoszeniu błędu przez komponent potomny. Otrzymuje zgłoszony błąd jako argument i powinna zwrócić wartość w celu aktualizacji stanu komponentu, aby wskazać, że wystąpił błąd (np. ustawiając flagę hasError na true).
componentDidCatch(error, info): Ta metoda cyklu życia jest wywoływana po zgłoszeniu błędu przez komponent potomny. Otrzymuje zgłoszony błąd jako argument, wraz z obiektem info zawierającym informacje o tym, który komponent zgłosił błąd. Można użyć tej metody do logowania błędu do serwisu takiego jak Sentry czy Bugsnag.

Oto podstawowy przykład komponentu Error Boundary:


class ErrorBoundary extends React.Component {
  constructor(props) {
    super(props);
    this.state = {
      hasError: false,
      error: null,
      errorInfo: null
    };
  }

  static getDerivedStateFromError(error) {
    // Zaktualizuj stan, aby następne renderowanie pokazało zapasowy interfejs.
    return {
      hasError: true,
      error: error
    };
  }

  componentDidCatch(error, info) {
    // Przykładowy "componentStack":
    //   in ComponentThatThrows (created by App)
    //   in MyErrorBoundary (created by App)
    //   in div (created by App)
    //   in App
    console.error("Caught an error:", error, info);
    this.setState({
        errorInfo: info.componentStack
    });
    // Możesz również zalogować błąd do serwisu raportowania błędów
    //logErrorToMyService(error, info.componentStack);
  }

  render() {
    if (this.state.hasError) {
      // Możesz renderować dowolny niestandardowy zapasowy interfejs
      return (
        <div>
          <h2>Coś poszło nie tak.</h2>
          <p>Błąd: {this.state.error ? this.state.error.message : "Wystąpił nieznany błąd."}</p>
          <details style={{ whiteSpace: 'pre-wrap' }}>
            {this.state.errorInfo && this.state.errorInfo}
          </details>
        </div>
      );
    }

    return this.props.children; 
  }
}

Aby użyć Error Boundary, wystarczy opakować drzewo komponentów, które chcesz chronić:


<ErrorBoundary>
  <MyComponentThatMightThrow/>
</ErrorBoundary>

Praktyczne przykłady użycia Error Boundary

Przyjrzyjmy się kilku praktycznym scenariuszom, w których Error Boundaries mogą być szczególnie przydatne:

1. Obsługa błędów API

Podczas pobierania danych z API mogą wystąpić błędy z powodu problemów z siecią, problemów z serwerem lub nieprawidłowych danych. Można opakować komponent, który pobiera i wyświetla dane, komponentem Error Boundary, aby płynnie obsłużyć te błędy.


function UserProfile() {
  const [user, setUser] = React.useState(null);
  const [isLoading, setIsLoading] = React.useState(true);

  React.useEffect(() => {
    async function fetchData() {
      try {
        const response = await fetch('/api/user');
        if (!response.ok) {
          throw new Error(`HTTP error! status: ${response.status}`);
        }
        const data = await response.json();
        setUser(data);
      } catch (error) {
        // Błąd zostanie przechwycony przez ErrorBoundary
        throw error; 
      } finally {
        setIsLoading(false);
      }
    }

    fetchData();
  }, []);

  if (isLoading) {
    return <p>Ładowanie profilu użytkownika...</p>;
  }

  if (!user) {
    return <p>Brak dostępnych danych użytkownika.</p>;
  }

  return (
    <div>
      <h2>{user.name}</h2>
      <p>Email: {user.email}</p>
    </div>
  );
}

function App() {
  return (
    <ErrorBoundary>
      <UserProfile />
    </ErrorBoundary>
  );
}

W tym przykładzie, jeśli wywołanie API nie powiodło się lub zwróciło błąd, Error Boundary przechwyci błąd i wyświetli zapasowy interfejs użytkownika (zdefiniowany w metodzie render komponentu Error Boundary). Zapobiega to awarii całej aplikacji i dostarcza użytkownikowi bardziej informacyjny komunikat. Można rozszerzyć zapasowy interfejs, aby zapewnić opcję ponowienia żądania.

2. Obsługa błędów bibliotek firm trzecich

Podczas korzystania z bibliotek firm trzecich możliwe jest, że mogą one zgłaszać nieoczekiwane błędy. Opakowanie komponentów korzystających z tych bibliotek w Error Boundaries może pomóc w płynnej obsłudze tych błędów.

Rozważmy hipotetyczną bibliotekę do tworzenia wykresów, która od czasu do czasu zgłasza błędy z powodu niespójności danych lub innych problemów. Można opakować komponent wykresu w następujący sposób:


function MyChartComponent() {
  try {
    // Renderuj wykres za pomocą biblioteki firmy trzeciej
    return <Chart data={data} />;
  } catch (error) {
    // Ten blok catch nie będzie skuteczny w przypadku błędów cyklu życia komponentu React
    // Jest on przeznaczony głównie dla błędów synchronicznych w tej konkretnej funkcji.
    console.error("Error rendering chart:", error);
    // Rozważ zgłoszenie błędu, aby został przechwycony przez ErrorBoundary
    throw error; // Ponowne zgłoszenie błędu
  }
}

function App() {
  return (
    <ErrorBoundary>
      <MyChartComponent />
    </ErrorBoundary>
  );
}

Jeśli komponent Chart zgłosi błąd, Error Boundary go przechwyci i wyświetli zapasowy interfejs. Zauważ, że blok try/catch wewnątrz MyChartComponent przechwyci tylko błędy w funkcji synchronicznej, a nie w cyklu życia komponentu. Dlatego ErrorBoundary jest tutaj kluczowy.

3. Obsługa błędów renderowania

Błędy mogą wystąpić podczas procesu renderowania z powodu nieprawidłowych danych, niepoprawnych typów propsów lub innych problemów. Error Boundaries mogą przechwycić te błędy i zapobiec awarii aplikacji.


function DisplayName({ name }) {
  if (typeof name !== 'string') {
    throw new Error('Imię musi być ciągiem znaków');
  }

  return <h2>Witaj, {name}!</h2>;
}

function App() {
  return (
    <ErrorBoundary>
      <DisplayName name={123} />  <!-- Niepoprawny typ propsa -->
    </ErrorBoundary>
  );
}

W tym przykładzie komponent DisplayName oczekuje, że props name będzie ciągiem znaków. Jeśli zamiast tego zostanie przekazana liczba, zostanie zgłoszony błąd, a Error Boundary go przechwyci i wyświetli zapasowy interfejs.

Error Boundaries a procedury obsługi zdarzeń

Jak wspomniano wcześniej, Error Boundaries nie przechwytują błędów występujących w procedurach obsługi zdarzeń. Dzieje się tak, ponieważ procedury obsługi zdarzeń są zazwyczaj asynchroniczne, a Error Boundaries przechwytują tylko błędy występujące podczas renderowania, w metodach cyklu życia i w konstruktorach.

Aby obsłużyć błędy w procedurach obsługi zdarzeń, należy użyć tradycyjnego bloku try...catch wewnątrz funkcji obsługi zdarzenia.


function MyComponent() {
  const handleClick = () => {
    try {
      // Jakiś kod, który może zgłosić błąd
      throw new Error('Wystąpił błąd w procedurze obsługi zdarzenia');
    } catch (error) {
      console.error('Przechwycono błąd w procedurze obsługi zdarzenia:', error);
      // Obsłuż błąd (np. wyświetl komunikat o błędzie użytkownikowi)
    }
  };

  return <button onClick={handleClick}>Kliknij mnie</button>;
}

Globalna obsługa błędów

Chociaż Error Boundaries są doskonałe do obsługi błędów w drzewie komponentów React, nie obejmują wszystkich możliwych scenariuszy błędów. Na przykład, nie przechwytują błędów występujących poza komponentami React, takich jak błędy w globalnych nasłuchiwaczach zdarzeń lub błędy w kodzie, który uruchamia się przed inicjalizacją Reacta.

Aby obsłużyć tego typu błędy, można użyć procedury obsługi zdarzenia window.onerror.


window.onerror = function(message, source, lineno, colno, error) {
  console.error('Globalna procedura obsługi błędów:', message, source, lineno, colno, error);
  // Zaloguj błąd do serwisu takiego jak Sentry czy Bugsnag
  // Wyświetl globalny komunikat o błędzie użytkownikowi (opcjonalnie)
  return true; // Zapobiegaj domyślnemu zachowaniu obsługi błędów
};

Procedura obsługi zdarzenia window.onerror jest wywoływana za każdym razem, gdy wystąpi nieprzechwycony błąd JavaScript. Można jej użyć do zalogowania błędu, wyświetlenia globalnego komunikatu o błędzie użytkownikowi lub podjęcia innych działań w celu obsłużenia błędu.

Ważne: Zwrócenie true z procedury obsługi zdarzenia window.onerror zapobiega wyświetleniu przez przeglądarkę domyślnego komunikatu o błędzie. Należy jednak pamiętać o doświadczeniu użytkownika; jeśli pomijasz domyślny komunikat, upewnij się, że dostarczasz jasną i informacyjną alternatywę.

Dobre praktyki stosowania Error Boundaries

Oto kilka dobrych praktyk, o których warto pamiętać podczas korzystania z Error Boundaries:

Umieszczaj Error Boundaries strategicznie: Opakowuj różne części aplikacji komponentami Error Boundary, aby izolować błędy i zapobiegać ich kaskadowemu rozprzestrzenianiu. Rozważ opakowanie całych ścieżek (routes) lub głównych sekcji interfejsu.
Dostarczaj informacyjny zapasowy interfejs: Zapasowy interfejs powinien informować użytkownika o wystąpieniu błędu i potencjalnie oferować sposób na odzyskanie. Unikaj wyświetlania ogólnych komunikatów o błędach, takich jak "Coś poszło nie tak".
Loguj błędy: Używaj metody cyklu życia componentDidCatch do logowania błędów do serwisu takiego jak Sentry czy Bugsnag. Pomoże to w śledzeniu pierwotnej przyczyny problemów i poprawie stabilności aplikacji.
Nie używaj Error Boundaries do obsługi oczekiwanych błędów: Error Boundaries są przeznaczone do obsługi nieoczekiwanych błędów. W przypadku oczekiwanych błędów (np. błędów walidacji, błędów API) używaj bardziej specyficznych mechanizmów obsługi błędów, takich jak bloki try...catch lub niestandardowe komponenty do obsługi błędów.
Rozważ wiele poziomów Error Boundaries: Możesz zagnieżdżać Error Boundaries, aby zapewnić różne poziomy obsługi błędów. Na przykład, możesz mieć globalny Error Boundary, który przechwytuje wszelkie nieobsłużone błędy i wyświetla ogólny komunikat o błędzie, oraz bardziej specyficzne Error Boundaries, które przechwytują błędy w określonych komponentach i wyświetlają bardziej szczegółowe komunikaty.
Nie zapominaj o renderowaniu po stronie serwera: Jeśli używasz renderowania po stronie serwera, musisz również obsługiwać błędy na serwerze. Error Boundaries działają na serwerze, ale może być konieczne użycie dodatkowych mechanizmów obsługi błędów, aby przechwycić błędy występujące podczas początkowego renderowania.

Zaawansowane techniki Error Boundary

1. Użycie Render Prop

Zamiast renderować statyczny zapasowy interfejs, można użyć "render prop", aby zapewnić większą elastyczność w obsłudze błędów. Render prop to props będący funkcją, której komponent używa do renderowania czegoś.


class ErrorBoundary extends React.Component {
  // ... (tak jak poprzednio)

  render() {
    if (this.state.hasError) {
      // Użyj render prop do renderowania zapasowego interfejsu
      return this.props.fallbackRender(this.state.error, this.state.errorInfo);
    }

    return this.props.children;
  }
}

function App() {
  return (
    <ErrorBoundary fallbackRender={(error, errorInfo) => (
      <div>
        <h2>Coś poszło nie tak!</h2>
        <p>Błąd: {error.message}</p>
        <details style={{ whiteSpace: 'pre-wrap' }}>
          {errorInfo.componentStack}
        </details>
      </div>
    )}>
      <MyComponentThatMightThrow/>
    </ErrorBoundary>
  );
}

Pozwala to na dostosowanie zapasowego interfejsu dla każdego Error Boundary indywidualnie. Props fallbackRender otrzymuje błąd i informacje o błędzie jako argumenty, co pozwala na wyświetlanie bardziej szczegółowych komunikatów o błędach lub podejmowanie innych działań w zależności od błędu.

2. Error Boundary jako komponent wyższego rzędu (HOC)

Można utworzyć komponent wyższego rzędu (HOC), który opakowuje inny komponent w Error Boundary. Może to być przydatne do stosowania Error Boundaries w wielu komponentach bez konieczności powtarzania tego samego kodu.


function withErrorBoundary(WrappedComponent) {
  return class WithErrorBoundary extends React.Component {
    render() {
      return (
        <ErrorBoundary>
          <WrappedComponent {...this.props} />
        </ErrorBoundary>
      );
    }
  };
}

// Użycie:
const MyComponentWithErrorHandling = withErrorBoundary(MyComponentThatMightThrow);

Funkcja withErrorBoundary przyjmuje komponent jako argument i zwraca nowy komponent, który opakowuje oryginalny komponent w Error Boundary. Pozwala to na łatwe dodanie obsługi błędów do dowolnego komponentu w aplikacji.

Testowanie Error Boundaries

Ważne jest, aby testować komponenty Error Boundary, aby upewnić się, że działają poprawnie. Do testowania Error Boundaries można użyć bibliotek testujących, takich jak Jest i React Testing Library.

Oto przykład, jak przetestować Error Boundary za pomocą React Testing Library:


import { render, screen, fireEvent } from '@testing-library/react';
import ErrorBoundary from './ErrorBoundary';

function ComponentThatThrows() {
  throw new Error('Ten komponent zgłasza błąd');
}

test('renderuje zapasowy interfejs, gdy zostanie zgłoszony błąd', () => {
  render(
    <ErrorBoundary>
      <ComponentThatThrows />
    </ErrorBoundary>
  );

  expect(screen.getByText('Coś poszło nie tak.')).toBeInTheDocument();
});

Ten test renderuje komponent ComponentThatThrows, który zgłasza błąd. Następnie test sprawdza, czy wyświetlany jest zapasowy interfejs renderowany przez Error Boundary.

Error Boundaries a Komponenty Serwerowe (React 18+)

Wraz z wprowadzeniem Komponentów Serwerowych w React 18 i nowszych wersjach, Error Boundaries nadal odgrywają kluczową rolę w obsłudze błędów. Komponenty Serwerowe wykonują się na serwerze i wysyłają do klienta tylko wyrenderowany wynik. Chociaż podstawowe zasady pozostają takie same, istnieje kilka niuansów, które należy wziąć pod uwagę:

Logowanie błędów po stronie serwera: Upewnij się, że logujesz błędy występujące w Komponentach Serwerowych na serwerze. Może to wymagać użycia frameworka do logowania po stronie serwera lub wysyłania błędów do usługi śledzenia błędów.
Zapasowy interfejs po stronie klienta: Mimo że Komponenty Serwerowe renderują się na serwerze, nadal trzeba zapewnić zapasowy interfejs po stronie klienta na wypadek błędów. Zapewnia to spójne doświadczenie użytkownika, nawet jeśli serwer nie zdoła wyrenderować komponentu.
Strumieniowe SSR: Podczas korzystania ze strumieniowego renderowania po stronie serwera (SSR), błędy mogą wystąpić w trakcie procesu strumieniowania. Error Boundaries mogą pomóc w płynnej obsłudze tych błędów, renderując zapasowy interfejs dla dotkniętego strumienia.

Obsługa błędów w Komponentach Serwerowych to rozwijający się obszar, dlatego ważne jest, aby być na bieżąco z najnowszymi dobrymi praktykami i zaleceniami.

Częste pułapki do uniknięcia

Nadmierne poleganie na Error Boundaries: Nie używaj Error Boundaries jako substytutu właściwej obsługi błędów w komponentach. Zawsze staraj się pisać solidny i niezawodny kod, który płynnie obsługuje błędy.
Ignorowanie błędów: Upewnij się, że logujesz błędy przechwycone przez Error Boundaries, aby móc zidentyfikować pierwotną przyczynę problemów. Nie ograniczaj się do wyświetlania zapasowego interfejsu i ignorowania błędu.
Używanie Error Boundaries do błędów walidacji: Error Boundaries nie są odpowiednim narzędziem do obsługi błędów walidacji. Zamiast tego używaj bardziej specyficznych technik walidacji.
Nietestowanie Error Boundaries: Testuj swoje komponenty Error Boundary, aby upewnić się, że działają poprawnie.

Wnioski

Error Boundaries to potężne narzędzie do budowania solidnych i niezawodnych aplikacji React. Dzięki zrozumieniu, jak skutecznie implementować i używać Error Boundaries, można poprawić doświadczenie użytkownika, zapobiegać awariom aplikacji i upraszczać debugowanie. Pamiętaj, aby strategicznie umieszczać Error Boundaries, dostarczać informacyjny zapasowy interfejs, logować błędy i dokładnie testować swoje Error Boundaries.

Postępując zgodnie z wytycznymi i dobrymi praktykami przedstawionymi w tym przewodniku, możesz zapewnić, że Twoje aplikacje React będą odporne na błędy i zapewnią pozytywne doświadczenia użytkownikom.