Как исправить 500 на Vercel
Ошибка 500 на Vercel означает, что приложение сломалось уже во время работы в production. В этом гайде разберём, как искать runtime errors, проверять environment variables, API routes, build logs и server logs, а также как безопасно откатывать deployment и восстанавливать production.
Что означает ошибка 500
Ошибка 500 означает внутреннюю ошибку сервера: приложение запустилось, но сломалось во время выполнения.
В отличие от 404, route существует, но код внутри страницы, API или server-side logic вызывает сбой.
На Vercel 500 ошибки часто связаны с environment variables, API integrations, server functions или runtime exceptions.
- Runtime error.
- Ошибка API.
- Отсутствующая environment variable.
- Ошибка базы данных.
- Ошибка server-side rendering.
- Ошибка fetch или external API.
- Неправильная production-конфигурация.
Почему 500 появляется только в production
Локально проект может работать нормально, но production environment отличается: другие variables, другой runtime, другие ограничения и другие данные.
Часто ошибка проявляется только после deploy, потому что production использует реальные API, домен или серверные функции.
- Environment variables отсутствуют.
- API ключи не добавлены.
- Runtime отличается от local.
- Build успешен, но код падает во время выполнения.
- Production использует другие URL.
- Ошибка возникает только на сервере.
- Данные в production отличаются от local.
Сначала откройте build logs и runtime logs
Ошибку 500 нельзя нормально чинить без логов. Первое действие — открыть deployment logs и посмотреть первую реальную ошибку.
Важно отличать build error от runtime error: build может проходить успешно, а production всё равно будет ломаться.
- Откройте Deployments в Vercel.
- Найдите production deployment.
- Проверьте build logs.
- Проверьте runtime logs.
- Найдите первую ошибку.
- Не исправляйте всё подряд одновременно.
- Сначала локализуйте источник ошибки.
Environment variables — самая частая причина 500
Если environment variables отсутствуют или названы неправильно, production может падать даже при успешном deploy.
Локально .env.local может существовать, а в Vercel production environment variables ещё не добавлены.
- Проверьте Environment Variables в Vercel.
- Проверьте названия ключей.
- Проверьте Production environment.
- Убедитесь, что переменные доступны после redeploy.
- Не храните секреты в коде.
- После изменения env сделайте redeploy.
- Проверьте, что API получает нужные значения.
API routes и external services
Ошибка 500 часто возникает внутри API route: запрос к OpenAI, Telegram, Stripe, базе данных или внешнему сервису возвращает ошибку.
Production environment может иметь ограничения, которых нет локально.
- Проверьте API endpoints.
- Проверьте статус внешнего API.
- Проверьте timeout.
- Проверьте fetch errors.
- Проверьте rate limits.
- Проверьте credentials.
- Проверьте response handling.
Ошибки server-side rendering и Next.js
В Next.js ошибки могут происходить во время server-side rendering: например, если сервер пытается использовать window, localStorage или browser-only APIs.
Такие ошибки часто не видны локально в dev mode, но ломают production runtime.
- Проверьте server-side код.
- Не используйте browser APIs на сервере.
- Проверьте dynamic imports.
- Проверьте async data fetching.
- Проверьте generateMetadata.
- Проверьте layout/page rendering.
- Проверьте server actions, если используются.
Build error vs runtime error
Build error означает, что проект вообще не собрался. Runtime error означает, что build прошёл, но приложение упало уже после запуска.
Для диагностики важно понимать, на каком этапе происходит сбой.
- Build error виден во время deploy.
- Runtime error появляется уже на production URL.
- Build logs показывают compile проблемы.
- Runtime logs показывают server exceptions.
- Иногда build успешен, но API ломается позже.
- Runtime ошибки часто связаны с данными и env.
- Не путайте build success с production stability.
Как безопасно диагностировать 500
При production error важно не вносить хаотичные изменения. Лучше проверить систему по слоям: deployment, env, API, routes, runtime.
Для AIWEBNET workflow безопаснее чинить ошибки маленькими commit и проверять preview deployment.
- Проверьте последний commit.
- Сравните рабочий и нерабочий deploy.
- Проверьте environment variables.
- Проверьте API routes.
- Проверьте runtime logs.
- Проверьте recent changes.
- Проверьте production URL в incognito.
- Проверяйте изменения через preview deployments.
Rollback: как быстро вернуть рабочий production
Если production сломан, сначала нужно вернуть стабильную версию, а уже потом искать причину ошибки.
Vercel хранит историю deployments, поэтому обычно можно откатиться на предыдущий рабочий deploy.
- Откройте Deployments.
- Найдите последний стабильный deploy.
- Проверьте его работоспособность.
- Используйте rollback или Promote to Production, если доступно.
- Проверьте production URL после отката.
- Зафиксируйте причину ошибки.
- Исправьте проблему в отдельной branch.
Частые причины 500 на Vercel
Большинство production 500 ошибок повторяются из проекта в проект: env, API, server rendering, runtime exceptions и broken integrations.
Важно научиться быстро находить источник проблемы, а не просто перезапускать deploy.
- Missing environment variable.
- Ошибка API integration.
- Неверный fetch URL.
- Database connection error.
- Browser API используется на сервере.
- Runtime exception.
- Ошибка async rendering.
- Ошибка server actions.
- Production использует старую переменную.
- Deploy успешен, но приложение ломается после запуска.
Как проверить production после исправления
После исправления ошибки важно проверить не только главную страницу, но и все критические сценарии пользователя.
Особенно важно проверить API, формы, SEO и внутренние routes.
- Production URL открывается.
- Нет 500 ошибок.
- API routes отвечают корректно.
- Формы работают.
- Внутренние страницы открываются.
- Console errors отсутствуют.
- Network requests успешны.
- Sitemap открывается.
- robots.txt доступен.
- Canonical корректный.
Production checklist для 500 ошибок
Этот checklist помогает проверить основные production-риски до отправки сайта пользователям или в индексацию.
Особенно полезен после deploy, refactor или подключения новых API.
- Build проходит.
- Runtime logs чистые.
- Environment variables добавлены.
- API работает.
- Нет server exceptions.
- Production URL стабилен.
- Preview deployment проверен.
- Rollback path известен.
- Внутренние страницы работают.
- SEO-страницы открываются.
- Нет критических network errors.
Связанные гайды AIWEBNET
500 ошибки часто связаны с runtime, API и environment variables. После исправления проверьте deploy workflow и routes.
Что делать дальше
После исправления 500 ошибок важно стабилизировать workflow: проверять preview deployments, делать маленькие commit и следить за production логами.
Для AIWEBNET важно, чтобы SEO, guides, blog и AI-инструменты не ломались после обновлений.
- Проверяйте preview deployments.
- Делайте маленькие commit.
- Следите за runtime logs.
- Проверяйте environment variables.
- Настройте rollback workflow.
- Проверяйте production после deploy.
- Следите за Search Console и coverage.