Если npm build падает при деплое, backend может быть живым, но новая верстка, стили и JavaScript не попадают на сайт. Иногда из-за этого полностью ломается интерфейс.

Частая ситуация: локально сборка проходит, а на сервере падает. Причина почти всегда в отличиях окружения или в скрытых зависимостях от переменных, путей и версии Node.js.

Коротко: нужно сверить Node.js, npm, lock-файл, переменные окружения, память и команду сборки.

Почему это ломается

Build ломается из-за старой версии Node.js, несовместимого npm, отсутствующего .env, различий npm install и npm ci, нехватки памяти, путей с учетом регистра, ошибок TypeScript или пакетов, которые работают только в dev-режиме.

Что проверяю в первую очередь

  • какая версия Node.js и npm на сервере
  • используется ли package-lock или yarn/pnpm lock
  • какая команда запускается при деплое
  • есть ли нужные переменные окружения
  • полный лог ошибки сборки

Как я это чиню

Я воспроизвожу сборку в серверном окружении и сравниваю ее с локальной: версии, зависимости, env, пути и выходную директорию.

  • настраиваю правильную версию Node.js
  • привожу установку зависимостей к lock-файлу
  • добавляю недостающие env-переменные
  • исправляю ошибки TypeScript, импортов и путей
  • обновляю deploy-команду и проверяю результат сборки

Что подготовить перед обращением

  • лог npm build
  • package.json и lock-файл
  • версию Node.js локально и на сервере
  • доступ к серверу или CI
  • название сборщика: Vite, Webpack, Next.js или другой

Как выглядит нормальный результат

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

Чего лучше не делать

Не удаляйте lock-файл и node_modules наугад без фиксации версий. Это может изменить дерево зависимостей и добавить новые проблемы.

Вопросы и ответы

Почему npm install проходит, а npm build падает?

Установка зависимостей и сборка проверяют разные вещи. Build может упасть на TypeScript, env или импортах.

Что лучше для деплоя: npm install или npm ci?

Для повторяемого деплоя обычно лучше npm ci, если lock-файл корректный.

Можно ли собирать локально и загружать dist?

Да, если это подходит процессу проекта. Но серверная сборка все равно должна быть понятной и воспроизводимой.

Почему ошибка только на Linux-сервере?

Часто из-за регистра в путях файлов: Windows прощает Import.jsx вместо import.jsx, Linux - нет.

Нужна похожая задача?

Напишите в Telegram @rabotator_support или оставьте заявку на сайте. Коротко опишите проблему, приложите ссылку, скриншот или лог ошибки, и я подскажу, с чего безопасно начать исправление.

Итог

Npm build при деплое нужно чинить через повторяемое окружение: версии Node.js, lock-файл, env и команда сборки должны быть зафиксированы.