Почему падает деплой, хотя локально всё работает — 3 причины, с которых начать

Знакомая боль: локально приложение запускается с первого раза, ты гордо нажимаешь «задеплоить» — и получаешь холодное Build failed. Первая мысль: «но у меня же всё работает!». Вот что сразу успокаивает: сервер не капризничает, он почти всегда спотыкается об одну из трёх вещей. И каждую видно в логах сборки. Сначала открой их (в Vercel, Netlify, Render это вкладка с логами деплоя) — причина обычно прямым текстом в красной строке. Разберём тройку лидеров, начиная с самой частой.

Если деплой для тебя пока в новинку — загляни сперва в что значит «задеплоить».

Симптом

Локально всё ок, а на хостинге сборка падает с ошибкой, или собирается, но сайт открывается белым/с ошибкой 500. Дальше — почему.

Причина 1. Переменные окружения не доехали (самая частая)

Локально ключи и адреса лежат у тебя в файле .env. А этот файл намеренно не попадает в git — иначе ты слил бы секреты. Значит, на сервере его нет, и код падает: «не найден API-ключ», «undefined».

Как проверить: в логах ищи слова вроде undefined, missing, имя переменной или API key not found. Собери список всего, что ты читаешь из окружения.

Как починить: в панели хостинга есть раздел Environment Variables. Внеси туда руками каждую переменную из своего .env — теми же именами. Пересобери. Про сам механизм — переменные окружения.

Причина 2. Версии и зависимости не совпали

«Работает на моём компьютере» часто значит «работает на моей версии Node и моих пакетах». На сервере версия другая, или какой-то пакет ты поставил локально, но не записал в проект.

Как проверить: в логах — module not found, cannot find package, или ошибка про версию Node. Проверь, что файл блокировки (package-lock.json, pnpm-lock.yaml) закоммичен, и что нужный пакет есть в package.json, а не только у тебя в папке.

Как починить: добавь недостающий пакет в зависимости (npm install имя и закоммить изменения в package.json + lock-файл). Если ругается на версию Node — задай её явно в настройках проекта на хостинге, ту же, что локально.

Причина 3. Регистр букв в путях (ловушка Mac/Windows → Linux)

Невидимый убийца. На Mac и Windows файловая система не различает Header.js и header.js — для них это один файл. Серверы почти всегда на Linux, а он различает регистр строго. Импорт ./components/header, когда файл называется Header.js, локально работает, а на сервере — module not found.

Как проверить: в логе module not found, но сам файл вроде на месте. Сверь регистр в импорте и в имени файла буква в букву.

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

Как чинить, если в логах непонятно

Скопируй красную строку из лога целиком и отдай ИИ-помощнику: «вот ошибка деплоя, вот мой стек — в чём причина и как починить». Полный текст ошибки решает половину дела. Подробнее — как чинить баги вместе с ИИ.

Почему локально работает, а на сервере нет?

Потому что это две разные среды: другая ОС, другие версии, и нет твоего .env. «Работает у меня» проверяет только твой компьютер. Деплой проверяет всё остальное — поэтому он и ловит то, чего ты дома не видел.

Где вообще смотреть причину падения?

В логах сборки на хостинге, не в браузере. У Vercel, Netlify, Render это отдельная вкладка с пошаговым выводом деплоя. Красная строка там — твоя главная улика, начинай всегда с неё.