Docker build --target: собрать только нужный stage

Категория: docker · Язык: Dockerfile · Обновлено:

Флаг --target собирает только указанный stage из multi-stage Dockerfile. Это ускоряет CI, позволяет собрать тестовый образ или отладить промежуточный слой, не дожидаясь финального. Финальный образ при этом не затрагивается, если вы его не указали.

Описать stages и собрать нужный

Dockerfile
FROM alpine:3.20 AS builder
WORKDIR /src
COPY hello.txt .
RUN cp hello.txt /built.txt

FROM scratch AS runtime
COPY --from=builder /built.txt /built.txt
Bash
docker build --target builder -t app:builder .
docker run --rm app:builder cat /built.txt
docker build --target runtime -t app:runtime .

Первый build собирает только builder и позволяет запустить контейнер с инструментами сборки. Второй собирает финальный runtime из scratch. Без --target Docker выполнит все stages, необходимые финальному, включая builder, но не будет запускать лишние команды после него.

--target полезен для тестового stage (test), линтера и отладочного образа. В CI можно собрать test, прогнать тесты, а затем собрать runtime с кешем. Целевой stage должен существовать в Dockerfile; опечатка даст ошибку failed to solve: target stage ... could not be found.

Флаг работает с BuildKit; в старых сборщиках поведение может отличаться. Для multi-platform сборки комбинируйте --target с --platform и --push/--load. Не публикуйте промежуточный образ с инструментами и секретами: он может содержать лишние пакеты и переменные.

--target не отменяет multi-stage очистку: в финальный образ попадает только то, что скопировано явно. Проверьте размер через docker image history и убедитесь, что build-args с секретами не осели в слоях.

Документация: docker build --target, multi-stage builds.