Почему приложение работает локально, но падает на проде — 3 причины и фикс

Знакомая обида: у тебя на ноутбуке всё кликается и летает, ты деплоишь — а на проде белый экран или сухая ошибка 500. Код-то тот же самый! В этом и подвох. Проблема почти никогда не в коде — она в том, что локальная среда и продакшн — это два разных мира. Разберём три причины, на которые натыкаются 90% новичков, и как каждую поймать.

Почему так вообще бывает

Локально у твоего кода вокруг всё «своё»: твои файлы, твои настройки, твой адрес localhost. На сервере всё чужое — другая машина, другая операционка, никаких твоих локальных подпорок. Код одинаковый, а окружение вокруг него другое. Значит, ищем не баг в логике, а то, что было у тебя и не доехало до сервера.

Причина 1: переменные окружения не доехали

Самая частая, начни с неё. Ключи к базе, токены API, секреты ты держишь в файле .env локально. А этот файл не деплоится — он в .gitignore, и правильно, иначе секреты утекут. Итог: локально ключ есть, на проде — пусто, и приложение падает при первом же обращении к базе или API.

• Как проверить: открой панель хостинга (Vercel, Netlify, Railway) → раздел Environment Variables. Пусто или половины нет? Вот и причина.
• Как починить: пропиши там все переменные из своего .env вручную и передеплой. Подробнее — в разборах что такое переменные окружения и почему они не работают.

Причина 2: где-то захардкожен localhost

Пока ты разрабатываешь, фронтенд часто зовёт бэкенд по адресу http://localhost:3000. Локально это работает — оба крутятся у тебя. На проде localhost означает «сам сервер», а не твой бэкенд, и запросы уходят в пустоту. Тот же капкан — жёстко прописанный порт или путь, которого в проде нет.

• Как проверить: поищи в коде по слову localhost и по конкретным портам. Нашёл в адресах запросов — это оно.
• Как починить: вынеси адрес в переменную окружения. Локально — localhost, на проде — реальный домен. Один и тот же код, разные значения под средой.

Причина 3: файл есть у тебя, но не на сервере

Хитрая и обидная. Работает так: ты создал файл, приложение его использует — но на сервер он не попал. Два типовых сценария:

• Забыл закоммитить. Файл лежит у тебя, но не в гите — на сервер уехало всё, кроме него.

• Регистр в имени. Твой Mac или Windows не различает Header.js и header.js, а Linux-сервер — различает. Локально импорт находит файл, на проде — нет, и сборка рушится.

• Как проверить: глянь git status — файл в списке не отслеживаемых? А в импортах сверь регистр букв с реальным именем файла.

• Как починить: закоммить недостающее; приведи регистр в импортах ровно к имени файла. Мелочь, а прод роняет намертво.

Первым делом — откатись

Пока копаешь причину, прод лежит и пользователи видят ошибку. Не геройствуй вживую — сначала откатись на прошлую рабочую версию. Это вернёт людям работающий сайт за секунды, а ты уже спокойно, без пожара, пройдёшься по трём причинам выше. Порядок всегда один: сначала стабильность, потом разбор — как и при любом упавшем деплое.

Вопрос: как ловить это заранее, а не после?

Держи локальную среду похожей на прод: та же версия языка/платформы, реальные значения переменных в тесте, деплой маленькими кусками. И главное — не считай, что «работает у меня» = «работает у всех». Это две разные проверки. Раз в пару деплоев открой свой прод-URL с телефона по мобильному интернету, а не только localhost на ноуте — так ты видишь именно то, что видит пользователь.