Как да поправите вътрешна грешка 500 в Next.js Server Components

Отваряте маршрут в проект с Next.js App Router, страницата е работила преди миг, а сега браузърът показва Internal Server Error или HTTP отговор 500. Презареждането не помага. Клиентската конзола може да показва малко полезна информация, тъй като отказът е настъпил, докато Server Component се е изобразявал на сървъра.

Тази ситуация е достатъчно често срещана, за да изглежда загадъчна, но грешка 500 не е диагноза. Тя означава, че сървърът е срещнал неочаквано условие при обработката на заявката. Next.js може да върне грешка 500 за необработена приложна грешка, а Server Components са особено важни за проверка, тъй като могат да изпълняват достъп до данни, заявки към бази данни, проверки за удостоверяване и друга логика, валидна само на сървъра, по време на изобразяването.

Забележка за версията: към 11 септември 2026 г. официалната документация на Next.js посочва Next.js 16.3.4 като най-новата версия. Формулировката на грешките, оверлеите за разработка, поведението по време на изпълнение и логовете за внедряване могат да варират в зависимост от версията и хостинг платформата, затова използвайте стековия запис от собствения си проект като основно доказателство.

Какво обикновено причинява грешка 500 в Server Component?

В App Router Next.js използва Server Components по подразбиране. Официалната документация за Server и Client Components обяснява, че Server Components се изпълняват на сървъра и могат да извършват сървърна работа, като достъп до данни. Ако една от тези операции хвърли изключение и то не бъде обработено по начин, който води до валиден отговор или резервен вариант, заявката може да се провали.

Стъпка 1: Възпроизведете отказващия маршрут локално и прочетете изхода на сървъра

Започнете с най-лесно достъпното доказателство. Стартирайте същия проект локално с обичайната си команда за разработка, като npm run dev, и заявете точния маршрут, който се проваля. Не започвайте с промяна на кеша, надграждане на пакети или изтриване на lock файлове. Първо намерете първото смислено изключение в терминала, където работи Next.js.

Браузърът ви казва, че заявката е неуспешна; сървърният стеков запис е по-вероятно да ви каже защо. Търсете първия ред във вашия собствен приложен код, а не последния ред във вътрешностите на фреймуърка. Запишете маршрута, файла, номера на реда, типа на грешката и дали отказът настъпва при всяка заявка или само със специфични данни.

Ако проблемът възниква само в производствена среда, използвайте логовете за изпълнение на вашия хост. В Vercel официалното ръководство за логиране разграничава логовете за изграждане от логовете за изпълнение и обяснява, че записите за изпълнение могат да се филтрират по код на статуса и път на заявката. Vercel също така документира, че неуспех при извикване на функция може да върне грешка 500, когато изпълнителната среда крашне или възникне необработено изключение или отхвърляне.

Стъпка 2: Изолирайте извличането на данни и направете отказите явни

Server Components често се провалят, докато чакат отговор от външен API или база данни. Официалният урок на Next.js за извличане на данни показва Server Components, извършващи асинхронен сървърен достъп до данни. Третирайте всяка външна зависимост като възможна точка на отказ.

За fetch() разграничете мрежовия отказ от HTTP отговор с грешка. Отговор с неуспешен статус трябва да бъде проверен преди парсването или изобразяването на данните му. Малък wrapper прави истинския проблем видим в сървърните логове:

async function getData() {
  const apiUrl = process.env.API_URL;

  if (!apiUrl) {
    throw new Error('API_URL is not configured');
  }

  const response = await fetch(apiUrl, { cache: 'no-store' });

  if (!response.ok) {
    throw new Error(`Upstream request failed: ${response.status}`);
  }

  return response.json();
}

Не записвайте в логовете токени за достъп, бисквитки, заглавки за удостоверяване, пароли за бази данни или пълни URL адреси, съдържащи тайни. Кодът на статуса, името на целевия обект на заявката, ID за корелация и почистено съобщение за грешка обикновено са достатъчни, за да се идентифицира отказалата зависимост.

Стъпка 3: Проверете променливите на средата и границата сървър/клиент

Ако същият комит работи локално, но връща грешка 500 след внедряване, сравнете средите, преди да промените логиката на приложението. Уверете се, че всяка необходима сървърна променлива съществува в целевата среда за внедряване и че стойността сочи към услуга, достъпна от тази изпълнителна среда. Локалният файл .env не доказва, че производственото внедряване има същите стойности.

След това проверете границите на компонентите. Next.js Server Components са по подразбиране в App Router, докато интерактивният код, който се нуждае от състояние, ефекти, обработка на събития или браузърни API, принадлежи в Client Component. Официалният обучителен материал на Next.js демонстрира преместването на компонент, използващ useState, зад директива 'use client'. Някои грешки с границите се хващат по време на компилация, вместо да станат грешка 500, но елиминирането им ви предпазва от третиране на грешка в структурата на кода като срив в хостинга.

Проверете и всеки пакет, валиден само за сървъра, който предполага конкретна възможност на Node.js, файловата структура, нативен двоичен файл или мрежова среда. Зависимостта може да работи на една машина и да се провали в друга изпълнителна среда, ако тези допускания се различават.

Стъпка 4: Добавете правилната обработка на грешки, вместо да скривате изключението

След като коренната причина е известна, решете дали грешката е очаквана или неочаквана. Липсващ запис може да заслужава отговор not-found. Неуспешна валидация може да заслужава нормално съобщение. Неочаквано изключение трябва да бъде записано в логовете и да достигне до граница за грешки, вместо да бъде тихо превърнато в празни данни, които чупят нещо друго.

Next.js документира специалния файл error.tsx като граница за грешки за сегмент от маршрута за неочаквани грешки. Неговият компонент е Client Component и може да предложи повторен опит чрез предоставената функция reset. Официалното ръководство на Next.js за обработка на грешки също демонстрира използването на notFound(), когато поисканият ресурс не съществува.

'use client';

export default function Error({
  reset,
}: {
  reset: () => void;
}) {
  return (
    <main>
      <h2>Something went wrong.</h2>
      <button onClick={() => reset()}>Try again</button>
    </main>
  );
}

Границата за грешки подобрява това, което вижда потребителят; тя не поправя основното изключение. Запазете сървърния лог, който идентифицира причината, и не излагайте чувствителни стекови записи или тайни в интерфейса.

Стъпка 5: Проверете поправката в производствена версия

Сървърът за разработка е необходим за диагностика, но не е финалният тест. След като маршрутът работи локално, изпълнете производствено изграждане с мениджъра на пакети на вашия проект, стартирайте го в режим на производство, когато е практично, и заявете същия маршрут със същите релевантни условия за данни. След това проверете внедрената среда с отворени логове за изпълнение.

npm run build
npm start

Ако вашата хостинг платформа изгражда по различен начин от вашия лаптоп, тествайте и внедряване за преглед, преди да насочите промяната. Поправката е достоверна само когато маршрутът връща очаквания статус, изобразява очакваното съдържание и не се появява ново сървърно изключение за тази заявка.

Как да потвърдите, че грешка 500 е наистина поправена

• Предишно отказващият URL се зарежда многократно без HTTP отговор 500.
• Терминалът на сървъра или производствените логове за изпълнение вече не показват оригиналното изключение.
• Същата поправка оцелява при npm run build и изпълнение в режим на производство или внедряване за преглед.
• Необходимите променливи на средата присъстват в средата, където отказът е възникнал първоначално.
• Отказите на външни API или бази данни вече водят до контролиран път за грешки, вместо до необясним срив.
• Интерактивният код, валиден само за браузъра, е в Client Components, докато тайните и привилегированият достъп до данни остават на сървъра.
• Границата error.tsx предоставя на потребителите разумен резервен вариант за неочаквани откази на сегменти от маршрута.

Ако все още се проваля

Намалете маршрута, докато спре да се проваля. Временно заменете една зависимост по едно с известна безопасна стойност: първо извикването към базата данни, след това външния API, след това удостоверяването или търсенето на сесия, след това дочерните компоненти. Първата премахната операция, която кара грешка 500 да изчезне, идентифицира областта за разследване. Възстановете всяка зависимост след тестване, вместо да оставяте фалшиви данни в финалното приложение.

За проблем, възникващ само в производствена среда, сравнете точния внедрен комит, конфигурацията на Node/изпълнителната среда, променливите на средата, мрежовата достъпност и версиите на зависимостите. Ако платформата докладва код за грешка, специфичен за доставчика, използвайте официалната документация на доставчика за този точен код, вместо да приемате, че всяка грешка 500 има една и съща причина.

Ключовото правило за отстраняване на неизправности е просто: третирайте „Internal Error 500“ като симптом. Полезното доказателство е сървърното изключение, което се е случило непосредствено преди него. Намерете това изключение първо, направете отказалата зависимост явна, коригирайте средата или границата на кода, която я е предизвикала, и проверете резултата в същата изпълнителна среда, където е възникнал проблемът.