Почему падает 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 ГБ — этого мало почти любому современному фронтенду.
Как починить. По порядку:
- Подними лимит памяти в настройках Docker до 4–8 ГБ.
- Если падает в CI, где настройки не твои — уменьши аппетит сборки: собери фронтенд отдельно, а в образ клади уже готовые файлы (multi-stage сборка).
- Проверь, что не тащишь в образ лишнего — см. причину 1, она умеет косвенно съедать память.
Почему в CI падает, а локально собирается?
Потому что локально у тебя тёплый кэш и другая машина. В CI сборка каждый раз с нуля: там нет твоих слоёв, часто меньше памяти и другая архитектура. Если локально хочется воспроизвести ту же ситуацию — собери с --no-cache и явной платформой. Обычно после этого ошибка появляется и дома.
Что значит exit code 1 на шаге RUN?
Что упала та команда, которую ты в RUN написал, а не Docker. RUN npm ci с кодом 1 — это ошибка npm, и искать надо её текст выше по логу. Docker тут просто посыльный: он останавливает сборку, потому что любой ненулевой код на шаге считает провалом. Что вообще собой представляет образ и чем отличается от контейнера — в разборе что такое Docker, а как он соотносится с виртуалкой — в Docker или виртуальная машина.
Курс «Профессия 2027: ИИ-архитектор»: шаг за шагом от основ компьютера до своего приложения и первых клиентов. 543 коротких урока на телефоне.





