Как устроена сборка: слои и стадии
Образ — стопка слоёв: внизу слои базового образа из FROM, сверху — по слою на каждую строку RUN
и COPY. Docker берёт слой из кэша, если не изменились ни строка, ни файлы, которые она копирует, ни слои
выше. Первый изменённый слой пересобирается, и все ниже — тоже. Поэтому то, что меняется редко (список зависимостей), копируем раньше того, что меняется
каждый день (код и тексты).
Стадия — это FROM … AS имя и строки под ним. В итоговый образ попадает только последняя стадия, а из
предыдущих мы забираем нужное через COPY --from=имя:
стадия build — node:24.22.1-alpine
├── node, npm
├── node_modules — около 200 МБ
├── исходники сайта
└── dist/ — готовые страницы
│
│ COPY --from=build
▼
итоговый образ — nginx:1.31.8-alpine
├── nginx
├── /etc/nginx/conf.d/default.conf
└── /usr/share/nginx/html — страницы из dist/
На сервер уходит только нижняя часть: nginx на Alpine — десятки мегабайт — и страницы сайта. Node, компиляторы и исходники остаются на машине, где шла сборка.
Настройка
Пример — сайт на Astro: npm run build кладёт страницы в dist/. У другого генератора своя команда
и свой каталог, остальное то же.
Кладём .dockerignore рядом с Dockerfile
.git .env .env.* node_modules distБез него
COPY . .тащит в сборкуnode_modulesс ноутбука,.envс паролями и всю историю git. Чем это кончается — в «.dockerignore».Пишем Dockerfile в две стадии
# Стадия сборки: Node, зависимости, исходники FROM node:24.22.1-alpine AS build WORKDIR /app COPY package.json package-lock.json ./ RUN npm ci COPY . . RUN npm run build # Итоговый образ: nginx и готовые страницы FROM nginx:1.31.8-alpine COPY nginx.conf /etc/nginx/conf.d/default.conf COPY --from=build /app/dist/ /usr/share/nginx/html/ RUN nginx -tCOPY package.json package-lock.json ./иRUN npm ciстоят доCOPY . .: пока список зависимостей не менялся, оба слоя берутся из кэша, и правка текста пересобирает толькоCOPY . .иnpm run build.npm ci, а неnpm install: он ставит ровно то, что записано вpackage-lock.json, и падает, если lock-файл отстал отpackage.json. Так в образе те же версии, что проверяли.Теги образов — с полной версией:
node:24.22.1-alpine, а неnode:alpine— иначе через месяц та же сборка возьмёт другой Node («Docker», «Тег — не версия»).RUN nginx -tпроверяет конфиг при сборке: ошибка останавливает сборку, и образ со сломанным конфигом не появляется.Пишем nginx.conf
server { listen 80; root /usr/share/nginx/html; error_page 404 /404.html; location / { try_files $uri $uri/ =404; } }Astro кладёт страницу
/about/вabout/index.html:try_files $uri $uri/находит её,index.htmlnginx подставляет сам. Файл заменяетdefault.confиз образа nginx целиком.Собираем образ
docker build -t site:dev .Правим любую страницу и собираем ещё раз. В выводе у зависимостей —
CACHED:=> CACHED [build 3/6] COPY package.json package-lock.json ./ => CACHED [build 4/6] RUN npm ciЕсли
npm ciпошёл заново, а зависимости не меняли, — значит,COPY . .стоит выше него или изменилсяpackage.json: хватает правки поляversionилиscripts.Запускаем и открываем
docker run --rm -d --name site-test -p 127.0.0.1:8080:80 site:dev curl -sI http://127.0.0.1:8080/ | head -1 # HTTP/1.1 200 OK docker rm -f site-testПорт — на
127.0.0.1: проверка нужна только нам, наружу его не открываем («Порт только для хоста — на 127.0.0.1»).Ставим тег по коммиту
docker tag site:dev site:$(git rev-parse --short HEAD)По тегу коммита видно, что за версия на сервере, и к нему откатываемся. Как образ попадает на сервер без ручных шагов — «Деплой без SSH».
Если не работает
npm ci идёт заново после каждой правки текста
- Причина
COPY . .стоит вышеRUN npm ci: любой изменённый файл ломает кэш этого слоя и всех ниже.- Делаем
- Сначала
COPY package.json package-lock.json ./иRUN npm ci, потомCOPY . .— как в шаге 2.
Сборка начинается с transferring context на сотни мегабайт
- Причина
- Нет
.dockerignore: в контекст сборки уходятnode_modulesи.git. - Делаем
- Кладём
.dockerignoreрядом сDockerfile(«.dockerignore»).
npm ci can only install packages when your package.json and package-lock.json … are in sync
- Причина
- В
package.jsonпоменяли зависимость, аpackage-lock.jsonне обновили. - Делаем
npm installна своей машине и коммит обоих файлов.npm ciв сборке ставит строго по lock-файлу — поэтому его и берём.
На ноутбуке образ работает, на сервере — exec format error
- Причина
- Ноутбук на ARM собрал образ под
arm64, а сервер —amd64. - Делаем
docker build --platform linux/amd64 …или сборка на самом сервере либо в CI.
Сборка падает на последнем шаге: nginx: [emerg] … in /etc/nginx/conf.d/default.conf:5
- Причина
- Ошибка в
nginx.conf:RUN nginx -tпроверяет его при сборке. - Делаем
- Правим строку из сообщения. Так и задумано: сломанный конфиг остаётся в сборке, а работающий сайт его не получает.
Как проверить
В итоговом образе нет Node — он остался в стадии сборки:
docker run --rm site:dev sh -c 'command -v node || echo "node нет"'
# node нет
Страницы на месте, node_modules и исходников нет:
docker run --rm site:dev ls /usr/share/nginx/html | head -3
docker run --rm site:dev ls /app
# ls: /app: No such file or directory
Размер — nginx плюс страницы сайта:
docker image ls site:dev --format '{{.Repository}}:{{.Tag}}\t{{.Size}}'