Docker Buildx Build –target 사용법 완벽 가이드! 특정 Build Stage 실행하기

Dockerfile이 점점 복잡해지면 하나의 이미지 빌드 과정 안에서도 여러 단계(Stage)를 나누어 관리하게 됩니다.

예를 들어:

• 개발 환경 이미지
• 테스트 환경 이미지
• 최종 운영 이미지
• 빌드 전용 환경

등을 하나의 Dockerfile 안에서 관리할 수 있습니다.

이때 사용하는 것이 Docker Multi-stage Build입니다.

Docker Buildx Build에서는 특정 Stage만 선택하여 빌드할 수 있는 기능을 제공합니다.

바로 --target 옵션입니다.

예:

docker buildx build \
--target builder \
-t test-image:v1 .

Dockerfile 안에 정의된 특정 Stage까지만 실행할 수 있습니다.

이번 글에서는 Docker Buildx Build –target의 개념부터 Multi-stage Build 구조, 특정 Stage 실행 방법, 개발·테스트 활용 사례까지 자세히 알아보겠습니다.

Docker Buildx Build –target이란 무엇인가?

--target은 Dockerfile의 특정 Build Stage를 지정하는 옵션입니다.

기본 형식:

docker buildx build \
--target Stage이름 .

Dockerfile:

FROM node AS builder

RUN npm install


FROM nginx AS production

COPY --from=builder .

빌드:

docker buildx build \
--target builder .

builder Stage까지만 실행합니다.

Docker Multi-stage Build란?

Multi-stage Build는 하나의 Dockerfile에서 여러 개의 빌드 단계를 정의하는 방식입니다.

예:

FROM golang AS builder

RUN go build


FROM alpine

COPY --from=builder /app .

구조:

Stage 1

Builder 환경

↓

Stage 2

최종 이미지

불필요한 파일을 제거하여 이미지 크기를 줄일 수 있습니다.

Docker Buildx Build –target은 언제 사용하는가?

다음 상황에서 사용합니다.

• 개발용 Stage 테스트
• 빌드 과정 확인
• Debug 환경 생성
• 특정 단계 결과 확인
• CI/CD 단계 분리

특히 복잡한 Dockerfile 관리에서 유용합니다.

Docker Buildx Build –target 기본 사용법

Dockerfile:

FROM ubuntu AS base

RUN apt update


FROM base AS test

RUN echo "test"


FROM base AS production

RUN echo "production"

Stage 확인:

base

test

production

특정 Stage 빌드:

docker buildx build \
--target test \
-t app:test .

test Stage 결과가 생성됩니다.

Docker Buildx Build –target과 일반 Build 차이

일반 Build:

docker buildx build \
-t app:v1 .

기본적으로 마지막 Stage까지 실행합니다.

Target 사용:

docker buildx build \
--target test \
-t app:test .

원하는 Stage까지만 실행합니다.

Dockerfile Stage 이름 확인 방법

Dockerfile:

FROM python AS builder

FROM builder AS testing

FROM testing AS production

Stage 이름:

builder

testing

production

AS 뒤의 이름을 --target 값으로 사용합니다.

Docker Buildx Build –target 실무 활용 예제

테스트 환경 빌드

Dockerfile:

FROM node AS development

COPY . .

RUN npm install


FROM development AS test

RUN npm test


FROM nginx AS production

COPY --from=development /app .

테스트만 실행:

docker buildx build \
--target test \
-t app:test .

운영 이미지를 만들지 않고 테스트할 수 있습니다.

개발 환경과 운영 환경 분리

개발:

docker buildx build \
--target development \
-t app:dev .

운영:

docker buildx build \
--target production \
-t app:prod .

하나의 Dockerfile로 여러 환경을 관리할 수 있습니다.

CI/CD에서 Docker Buildx Build –target 활용

CI 단계:

테스트:

docker buildx build \
--target test \
-t app:test .

배포:

docker buildx build \
--target production \
-t app:prod \
--push .

빌드 목적에 따라 Stage를 분리할 수 있습니다.

Linux 서버 문제 해결

운영 서버 배포 전에 테스트 Stage만 확인하고 싶었습니다.

기존:

docker buildx build \
-t app:test .

문제:

전체 Production Stage까지 실행되어 빌드 시간이 오래 걸렸습니다.

Dockerfile 확인:

FROM node AS test

FROM nginx AS production

테스트 Stage만 실행:

docker buildx build \
--target test \
-t app:test .

결과:

Test Stage 완료

불필요한 Production 빌드를 줄이고 빠르게 검증할 수 있었습니다.

Docker Buildx Build –target 사용 시 주의사항

첫 번째는 지정한 Stage 이름이 Dockerfile에 존재해야 합니다.

두 번째는 Target Stage 이후 단계는 실행되지 않습니다.

세 번째는 최종 배포 이미지와 테스트 이미지를 구분해야 합니다.

네 번째는 Stage 구조를 명확하게 설계하는 것이 중요합니다.

Best Practice

Docker Buildx Build –target 활용 방법:

• Dockerfile Stage 이름을 명확하게 작성
• 개발·테스트·운영 Stage 분리
• CI/CD 단계별 Target 활용
• 불필요한 빌드 과정 제거
• Multi-stage Build와 함께 사용
• 운영 배포 전 테스트 Stage 검증

자주 묻는 질문

Docker Buildx Build –target은 무엇인가요?

Dockerfile의 특정 Build Stage만 실행하는 옵션입니다.

–target은 Dockerfile을 여러 개 만들어야 하나요?

아닙니다.

하나의 Dockerfile에서 여러 Stage를 관리할 수 있습니다.

운영 이미지에도 사용할 수 있나요?

가능합니다.

Production Stage를 지정하여 빌드할 수 있습니다.

Multi-stage Build와 함께 사용해야 하나요?

일반적으로 함께 사용하면 가장 효과적입니다.

마무리

Docker Buildx Build –target은 Multi-stage Dockerfile 환경에서 특정 빌드 단계만 실행할 수 있도록 해주는 중요한 옵션입니다.

개발, 테스트, 운영 환경을 하나의 Dockerfile에서 관리하면서 필요한 단계만 빠르게 실행할 수 있어 빌드 시간을 줄이고 효율적인 Docker 운영이 가능합니다.

특히 CI/CD 환경에서는 테스트와 배포 단계를 분리하는 데 매우 유용하며, 복잡한 Docker 프로젝트를 체계적으로 관리하는 핵심 기능입니다.