re:re:actable
Урок 053 минуты чтения

Что такое multi-stage build

На этой странице
Кратко

Multi-stage build — Dockerfile с несколькими FROM: каждый начинает новый stage со своим базовым образом. Ранние stages устанавливают зависимости и собирают приложение, а финальный копирует из них только готовый результат через COPY --from=stage. В итоговый образ не попадают компиляторы, devDependencies, исходники и кэш — он меньше, быстрее скачивается и содержит меньше уязвимостей.

Вопрос

Что такое multi-stage build и зачем он нужен?

Проблема одного stage

В однофазной сборке в production-образ попадают TypeScript, сборщики, devDependencies, тесты и исходники. Образ API на Node.js легко раздувается до 1 ГБ, хотя для запуска нужны только dist и production-зависимости.

Пример: API на Node.js

# syntax=docker/dockerfile:1
 
FROM node:24-alpine AS deps
WORKDIR /app
COPY package.json package-lock.json ./
RUN npm ci
 
FROM deps AS build
COPY . .
RUN npm run build
 
FROM node:24-alpine AS prod-deps
WORKDIR /app
COPY package.json package-lock.json ./
RUN npm ci --omit=dev
 
FROM node:24-alpine AS runner
WORKDIR /app
ENV NODE_ENV=production
COPY --from=prod-deps /app/node_modules ./node_modules
COPY --from=build /app/dist ./dist
COPY package.json ./
USER node
EXPOSE 3000
CMD ["node", "dist/main.js"]
deps ──▶ build ──────────────┐
                             ├──▶ runner (финальный образ)
prod-deps ───────────────────┘

BuildKit строит граф зависимостей и выполняет независимые stages параллельно (build и prod-deps), а stages, не нужные для цели, пропускает.

Пример: статика Vite за Nginx

FROM node:24-alpine AS build
WORKDIR /app
COPY package.json package-lock.json ./
RUN npm ci
COPY . .
RUN npm run build
 
FROM nginx:1.29-alpine
COPY nginx.conf /etc/nginx/conf.d/default.conf
COPY --from=build /app/dist /usr/share/nginx/html

Node.js нужен только для сборки, в production работает Nginx — образ весит около 50 МБ.

COPY --from и --target

COPY --from=build /app/dist ./dist            # из stage этого Dockerfile
COPY --from=nginx:1.29-alpine /etc/nginx/nginx.conf ./   # из любого образа
docker build --target build -t app:build .    # остановиться на stage build

--target удобен, чтобы из одного Dockerfile получить dev-образ, образ для тестов и production:

FROM deps AS dev
COPY . .
CMD ["npm", "run", "dev"]
 
FROM deps AS test
COPY . .
RUN npm test

Что даёт multi-stage

  • Меньший размер финального образа — быстрее pull и деплой.
  • Меньше пакетов — меньше уязвимостей и поверхность атаки.
  • Секреты и токены, нужные на этапе сборки, не попадают в финальный stage.
  • Разные базовые образы для сборки и запуска (например, node → distroless).
  • Параллельное выполнение независимых stages.

Частые ошибки

  • Копировать в финальный stage весь /app вместо нужных артефактов.
  • Оставлять devDependencies в runtime-образе.
  • Не называть stages и ссылаться по номеру (--from=0) — ломается при перестановке.
  • Думать, что секрет из build-stage «безопасен»: если его COPY в финальный stage, он там окажется.

Что важно помнить

  • В итоговый образ попадает только последний (или выбранный --target) stage.
  • Промежуточные stages остаются в кэше builder, но не в образе.
  • Для Nuxt multi-stage особенно удобен: финальный stage копирует только самодостаточный каталог .output, без node_modules.

Мини-шпаргалка

  • Несколько FROM ... AS name — несколько stages.
  • COPY --from=name — артефакты между stages.
  • --target — собрать конкретный stage.
  • Финальный stage: runtime + артефакты + USER + CMD.

Документация

Docker: Multi-stage builds, Docker: Building best practices.

Дочитали до конца?
Отметьте урок — прогресс сохранится в браузере.

Поиск

Поиск по урокам