Что такое 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/htmlNode.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.