re:re:actable
Урок 063 минуты чтения

Как работает global-error.tsx

На этой странице
Кратко

app/global-error.tsx задает запасной интерфейс для неперехваченных ошибок, включая ошибки корневого layout. При срабатывании он заменяет корневую оболочку приложения.

Вопрос

Что показать пользователю, если ошибка произошла в самой общей оболочке сайта?

Основная идея

Обычный error.tsx работает внутри layout своего сегмента. Поэтому он не может перехватить ошибку этого же layout: защитная граница расположена ниже него в дереве компонентов.

global-error.tsx находится выше корневой оболочки и подходит для такого случая. Он должен быть клиентским компонентом и самостоятельно возвращать <html> и <body>: прежний корневой layout уже не отображается.

Это резервный экран, а не универсальный обработчик любых ошибок JavaScript.

Какая граница ловит какую ошибку

global-error.tsx          ← ловит ошибку в app/layout.tsx (заменяет весь документ)
└─ app/layout.tsx
    ├─ app/error.tsx      ← ловит ошибки в app/page.tsx и вложенных сегментах,
    │                       но НЕ в app/layout.tsx (он выше границы)
    └─ dashboard/
        ├─ layout.tsx     ← его ошибку ловит app/error.tsx (граница уровнем выше)
        ├─ error.tsx      ← ловит ошибки dashboard/page.tsx и глубже
        └─ page.tsx
ФайлОбластьСвой <html>Стили и провайдеры корня
error.tsxСегмент и вложенныеНетЕсть
global-error.tsxВесь документ, включая корневой layoutДа, обязателенНет — оформить заново
not-found.tsxОжидаемое «нет ресурса»НетЕсть

Пример: минимальный резервный документ

// app/global-error.tsx
"use client";
 
export default function GlobalError({ reset }: { reset: () => void }) {
  return (
    <html lang="ru">
      <body>
        <main>
          <h1>Не удалось открыть приложение</h1>
          <p>Попробуйте восстановить экран или загрузить страницу заново.</p>
          <button onClick={() => reset()}>Восстановить экран</button>
          <button onClick={() => window.location.reload()}>
            Загрузить страницу заново
          </button>
        </main>
      </body>
    </html>
  );
}

Если неперехваченная ошибка возникнет в корневом layout, пользователь увидит этот документ вместо обычной шапки и страницы. reset() сбрасывает состояние границы ошибки и повторяет рендеринг ее содержимого; полная перезагрузка делает новый запрос документа.

Что важно помнить

reset() не гарантирует повторное получение серверных данных. В Next.js 16.3+ доступен retry(), который предназначен для повторной загрузки и рендеринга; в более ранней версии нужно учитывать доступный API. Этот пример использует совместимый reset() с его ограничением.

Обычные ошибки в обработчиках событий и отдельные асинхронные операции требуют собственной обработки. Ожидаемое отсутствие статьи лучше обрабатывать через notFound(), а ошибку проверки формы — показывать рядом с полем.

Стили и провайдеры из прежнего layout могут отсутствовать. Запасной экран должен оставаться понятным без них. Подробности серверной ошибки нельзя бездумно выводить пользователю; для диагностики используют серверные журналы.

Мини-шпаргалка

  • Файл располагается в корне app.
  • Нужны "use client", <html> и <body>.
  • Он может обработать ошибку корневой оболочки.
  • Сброс ошибки и повторная загрузка данных — разные действия.

Документация

Дочитали до конца?
Отметьте урок — прогресс сохранится в браузере.

Поиск

Поиск по урокам