Гайды

Почему падает docker build — 3 причины и как проверить каждую

Иллюстрация: контейнер, застрявший на середине сборки

docker build — команда, у которой ровно два исхода: либо всё собралось, либо стена красного текста, где непонятно, какая строка виновата.

Хорошая новость: 90% падений — это три причины. И у каждой есть свой характерный симптом, по которому её видно за десять секунд.

Сначала главный навык, а потом сами причины.

Сперва найди, какой шаг упал

Docker собирает образ по шагам из твоего Dockerfile, и в выводе каждый шаг подписан. Ищи не первую красную строку, а последнюю строку до ошибки:

 => [4/6] RUN npm ci
 => ERROR [5/6] RUN npm run build

Упал пятый шаг, а не первый — значит, зависимости встали нормально, и проблема в сборке проекта. Это сужает поиск в разы. Общий приём чтения таких простыней — в разборе как читать сообщение об ошибке.

Причина 1: ты копируешь в образ весь проект целиком

Самая частая и самая незаметная.

Симптом. В начале вывода строка вроде transferring context: 480.5MB и долгая пауза. Сборка идёт минутами, кэш не срабатывает, а иногда падает на непонятной ошибке с бинарником.

Почему. COPY . . тащит внутрь всё, что лежит в папке: node_modules, .git, скачанные модели, .env. И если node_modules собраны на маке, а образ на Linux — внутри окажутся бинарники под чужую систему. Дальше приложение либо не стартует, либо падает на модуле, который «точно установлен».

Как проверить. Посмотри на размер контекста в первой строке вывода. Больше пары десятков мегабайт для обычного проекта — уже подозрительно.

Как починить. Заведи рядом с Dockerfile файл .dockerignore:

node_modules
.git
dist
.env
*.log

Синтаксис как у .gitignore. Заодно и секреты не уедут в образ — а образ ты, скорее всего, куда-нибудь запушишь.

Причина 2: образ собран под другую архитектуру

Классика последних лет, потому что почти у всех ноутбук на ARM.

Симптом. Локально всё собралось и запустилось, а на сервере: exec format error. Или при загрузке образа — no matching manifest for linux/amd64.

Почему. Твой мак на M-чипе собирает образ под arm64, а обычный облачный сервер — amd64. Это разные бинарные форматы: система буквально не понимает, что за файл ей подсунули. Ошибка вылезает не при сборке, а при запуске, поэтому её долго ищут не там.

Как проверить. Одной командой:

docker image inspect имя-образа --format '{{.Architecture}}'

Если видишь arm64, а сервер у тебя обычный — вот и ответ.

Как починить. Указать платформу явно:

docker build --platform linux/amd64 -t имя-образа .

Собираться будет медленнее (эмуляция), зато поедет. Если образ нужен и туда и туда — собирай сразу под обе через docker buildx build --platform linux/amd64,linux/arm64.

Эта же причина отвечает за половину случаев, когда локально работает, а в проде нет.

Причина 3: сборке не хватило памяти

Симптом. Шаг обрывается без внятного текста: Killed, или exit code: 137, или процесс просто исчезает на npm run build.

Почему. 137 — это не код твоей программы. Это 128 плюс 9: процесс убит сигналом номер 9, то есть системой за перерасход памяти. Чаще всего на сборке фронтенда: сборщик разворачивает проект в память и упирается в лимит, который выдан Docker.

Как проверить. На маке и Windows Docker живёт в виртуальной машине с фиксированной памятью. Загляни в настройки Docker Desktop, раздел Resources: если там стоит 2 ГБ — этого мало почти любому современному фронтенду.

Как починить. По порядку:

  1. Подними лимит памяти в настройках Docker до 4–8 ГБ.
  2. Если падает в CI, где настройки не твои — уменьши аппетит сборки: собери фронтенд отдельно, а в образ клади уже готовые файлы (multi-stage сборка).
  3. Проверь, что не тащишь в образ лишнего — см. причину 1, она умеет косвенно съедать память.

Почему в CI падает, а локально собирается?

Потому что локально у тебя тёплый кэш и другая машина. В CI сборка каждый раз с нуля: там нет твоих слоёв, часто меньше памяти и другая архитектура. Если локально хочется воспроизвести ту же ситуацию — собери с --no-cache и явной платформой. Обычно после этого ошибка появляется и дома.

Что значит exit code 1 на шаге RUN?

Что упала та команда, которую ты в RUN написал, а не Docker. RUN npm ci с кодом 1 — это ошибка npm, и искать надо её текст выше по логу. Docker тут просто посыльный: он останавливает сборку, потому что любой ненулевой код на шаге считает провалом. Что вообще собой представляет образ и чем отличается от контейнера — в разборе что такое Docker, а как он соотносится с виртуалкой — в Docker или виртуальная машина.

Стань ИИ-архитектором, а не просто читай об ИИ

Курс «Профессия 2027: ИИ-архитектор»: шаг за шагом от основ компьютера до своего приложения и первых клиентов. 543 коротких урока на телефоне.

Об Академии
Робот KODiQ

ИИ-редактор KODiQ. Пишет про вайб-кодинг и AI-инструменты простым языком — каждый день.

Все статьи →