Обработка ошибок

Конвенция файлов error.js позволяет вам элегантно обрабатывать непредвиденные ошибки во время выполнения в вложенных маршрутах.

• Автоматически оборачивает сегмент маршрута и его вложенных потомков в React Error Boundary.
• Создаёт пользовательский интерфейс для ошибок, настроенный для конкретных сегментов, используя иерархию файловой системы для настройки гранулярности.
• Изолирует ошибки в затронутых сегментах, сохраняя функциональность остальной части приложения.
• Добавляет возможность попытки восстановления после ошибки без полной перезагрузки страницы.

Создайте пользовательский интерфейс для ошибок, добавив файл error.js внутри сегмента маршрута и экспортировав React-компонент:

'use client' // Error components must be Client Components
 
import { useEffect } from 'react'
 
export default function Error({
  error,
  reset,
}: {
  error: Error & { digest?: string }
  reset: () => void
}) {
  useEffect(() => {
    // Log the error to an error reporting service
    console.error(error)
  }, [error])
 
  return (
    <div>
      <h2>Something went wrong!</h2>
      <button
        onClick={
          // Attempt to recover by trying to re-render the segment
          () => reset()
        }
      >
        Try again
      </button>
    </div>
  )
}

Как работает error.js

• error.js автоматически создаёт React Error Boundary, который оборачивает вложенный дочерний сегмент или компонент page.js.
• React-компонент, экспортированный из файла error.js используется в качестве обрабатывающего компонента.
• Если во время выполнения произошла ошибка внутри Error Boundary, ошибка изолируется, и рендерится обрабатывающий компонент.
• Когда компонент обработки ошибок активен, макеты выше Error Boundary сохраняют своё состояние и остаются интерактивными, а компонент ошибки может отобразить функциональность восстановления от ошибки.

Восстановление после ошибок

Причина ошибки может быть временной. В этих случаях повторная попытка может решить проблему.

Компонент ошибки может использовать функцию reset() для запроса у пользователя попытки восстановления от ошибки. При выполнении функция попытается повторно отрисовать содержимое Error Boundary. При успехе, обрабатывающий компонент заменяется результатом повторной отрисовки.

'use client'
 
export default function Error({
  error,
  reset,
}: {
  error: Error & { digest?: string }
  reset: () => void
}) {
  return (
    <div>
      <h2>Something went wrong!</h2>
      <button onClick={() => reset()}>Try again</button>
    </div>
  )
}

Вложенные маршруты

React-компоненты, созданные через специальные файлы, рендерятся в определённой вложенной иерархии.

Например, вложенный маршрут с двумя сегментами, в которых оба содержат файлы layout.js и error.js, рендерятся в следующей упрощённой иерархии компонентов:

Вложенная иерархия компонентов имеет последствия для поведения файлов error.js по всему вложенному маршруту:

• Ошибки передаются вверх к ближайшему родительскому Error Boundary. Это означает, что файл error.js будет обрабатывать ошибки для всех его вложенных дочерних сегментов. Более или менее гранулированный пользовательский интерфейс для ошибок можно получить, разместив файлы error.js на разных уровнях вложенных папок маршрута.
• Error Boundary error.js не будет обрабатывать ошибки, выброшенные компонентом layout.js в том же сегменте, потому что Error Boundary вложен внутри компонента макета.

Обработка ошибок в макетах

Error Boundary error.js не перехватывают ошибки, выброшенные в компонентах layout.js или template.js того же сегмента. Эта намеренная иерархия сохраняет важный пользовательский интерфейс, используемый между родственными маршрутами (например, навигация), видимым и функциональным при возникновении ошибки.

Чтобы обработать ошибки внутри определённого макета или шаблона, разместите файл error.js в родительском сегменте макета.

Чтобы обработать ошибки внутри корневого макета или шаблона, используйте вариацию error.js под названием global-error.js.

Обработка ошибок в корневых макетах

Корневая app/error.js Error Boundary не перехватывает ошибки, выброшенные в корневом компоненте app/layout.js или app/template.js.

Чтобы обработать ошибки в этих корневых компонентах, используйте вариацию error.js под названием app/global-error.js, расположенную в корневом каталоге app.

В отличие от корневого error.js, Error Boundary global-error.js оборачивает всё приложение, и её обрабатывающий компонент заменяет корневой макет при активации. По этой причине важно отметить, что global-error.js должен определять свои теги <html> и <body>.

global-error.js - это пользовательский интерфейс для обработки ошибок с наименьшей гранулярностью и можно считать "общепринятой" обработкой ошибок для всего приложения. Вероятность его срабатывания низкая, т.к. корневые компоненты обычно менее динамичны, а другие Error Boundary error.js перехватывают большинство ошибок.

Даже если определена global-error.js, всё равно рекомендуется определить корневую error.js, обрабатывающий компонент которой будет рендериться внутри корневого макета, который включает в себя глобально используемый пользовательский интерфейс и фирменную символику.

'use client'
 
export default function GlobalError({
  error,
  reset,
}: {
  error: Error & { digest?: string }
  reset: () => void
}) {
  return (
    <html>
      <body>
        <h2>Something went wrong!</h2>
        <button onClick={() => reset()}>Try again</button>
      </body>
    </html>
  )
}

Важно знать:

• global-error.js активируется только в продакшене. В режиме разработки будет отображаться наша настройка перекрытия ошибок.

Обработка ошибок сервера

Если ошибка вызвана внутри компонента Server Component, Next.js передаст объект Error (лишённый конфиденциальной информации об ошибке в продакшене) ближайшему файлу error.js в качестве свойства error.

Защита конфиденциальной информации об ошибках

Во время продакшена объект Error , переданный клиенту, содержит только общее свойство message и digest.

Это мера безопасности для предотвращения утечки потенциально конфиденциальной информации об ошибке на клиент.

Свойство message содержит общее сообщение об ошибке, а свойство digest содержит автоматически сгенерированный хэш ошибки, который можно использовать для сопоставления соответствующей ошибки в логах сервера.

Во время разработки объект Error , переданный клиенту, будет сериализован и содержать message исходной ошибки для более удобной отладки.