Как работает 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>. - Он может обработать ошибку корневой оболочки.
- Сброс ошибки и повторная загрузка данных — разные действия.