Docker 프로젝트가 커지면 하나의 Dockerfile 안에서도 여러 환경을 관리해야 하는 경우가 많습니다.

예:

• 개발 환경
• 테스트 환경
• 빌드 환경
• 운영 환경
• 배포 전 검증 환경

이런 상황에서는 하나의 Dockerfile 안에 여러 개의 Build Stage를 작성하는 Multi-stage Build 방식을 사용합니다.

예:

FROM node:20 AS builder

RUN npm install

RUN npm run build


FROM nginx:latest AS production

COPY --from=builder /app/dist /usr/share/nginx/html

여기에는:

builder Stage

↓

production Stage

두 개의 빌드 단계가 존재합니다.

이때 원하는 Stage까지만 실행하기 위해 사용하는 옵션이 바로 **--target**입니다.

예:

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

특정 Build Stage까지만 실행할 수 있습니다.

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

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

--target은 Dockerfile 안에 정의된 특정 Build Stage를 선택하여 빌드하는 옵션입니다.

기본 형식:

docker buildx build \
--target Stage이름 .

예:

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

development Stage까지만 실행합니다.

Docker Multi-stage Build란 무엇인가?

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

기본 구조:

FROM ubuntu AS build

RUN build-command


FROM ubuntu AS production

COPY --from=build /app .

구조:

Build Stage

↓

Final Stage

장점:

• 최종 이미지 크기 감소
• 불필요한 파일 제거
• 개발 환경과 운영 환경 분리
• 보안 향상

Docker Buildx Build –target이 필요한 이유

일반적인 빌드:

docker buildx build \
-t app:v1 .

기본 동작:

Dockerfile 마지막 Stage 실행

하지만 개발 과정에서는 마지막 Stage까지 필요하지 않을 수 있습니다.

예:

테스트만 필요

↓

Test Stage 실행

↓

Production Stage 생략

이럴 때:

--target test

를 사용합니다.

Docker Buildx Build –target 기본 사용법

Dockerfile:

FROM ubuntu AS base

RUN apt update


FROM base AS test

RUN echo "Testing"


FROM base AS production

RUN echo "Production"

Stage:

base

test

production

Test Stage 실행

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

결과:

base 실행

↓

test 실행

↓

종료

Production Stage는 실행되지 않습니다.

Docker Buildx Build –target과 일반 Build 차이

일반 Build:

docker buildx build \
-t app:v1 .

실행:

base

↓

test

↓

production

마지막 Stage까지 진행합니다.

Target 사용:

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

실행:

base

↓

test

종료

필요한 단계까지만 실행합니다.

Docker Buildx Build –target Stage 이름 지정 방법

Dockerfile:

FROM node AS frontend

RUN npm install


FROM nginx AS server

Stage 이름:

frontend

server

사용:

docker buildx build \
--target frontend .

AS 뒤의 이름을 사용합니다.

Docker Buildx Build –target 실무 활용 예제

개발 환경과 운영 환경 분리

Dockerfile:

FROM node:20 AS development

COPY . .

RUN npm install


FROM development AS test

RUN npm test


FROM nginx AS production

COPY --from=development /app/dist .

개발:

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

테스트:

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

운영:

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

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

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

CI 과정:

코드 다운로드

↓

Test Stage 실행

↓

테스트 성공

↓

Production Stage 빌드

↓

배포

예:

테스트:

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

배포:

docker buildx build \
--target production \
-t company/app:v1 \
--push .

효율적인 Pipeline 구성이 가능합니다.

Linux 서버 문제 해결

운영 배포 전에 테스트 단계만 확인하려고 했습니다.

기존:

docker buildx build \
-t app:test .

문제:

Production Stage까지 실행

빌드 시간 증가

Dockerfile:

FROM node AS test

FROM nginx AS production

해결:

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

결과:

Test Stage 완료

Production 빌드 생략

불필요한 빌드 시간을 줄일 수 있었습니다.

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

첫 번째는 지정한 Stage 이름이 정확해야 합니다.

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

세 번째는 테스트용 이미지와 운영 이미지를 구분해야 합니다.

네 번째는 Multi-stage 구조를 먼저 설계하는 것이 중요합니다.

Best Practice

Docker Buildx Build –target 활용 방법:

• 개발·테스트·운영 Stage 분리
• Stage 이름 명확하게 작성
• CI/CD 단계별 Target 활용
• 불필요한 빌드 제거
• Multi-stage Build 적극 활용
• 운영 이미지 크기 최적화

자주 묻는 질문

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

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

Multi-stage Build에서만 사용할 수 있나요?

대부분 Multi-stage Build 환경에서 사용하지만 단일 Stage에서는 의미가 없습니다.

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

가능합니다.

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

Target을 사용하면 이미지 크기가 줄어드나요?

Target 자체가 줄이는 기능은 아니지만 필요한 Stage만 빌드하여 관리 효율을 높일 수 있습니다.

마무리

Docker Buildx Build –target은 복잡한 Docker 프로젝트를 효율적으로 관리하기 위한 중요한 옵션입니다.

하나의 Dockerfile 안에서 개발, 테스트, 운영 환경을 분리하고 필요한 단계만 실행할 수 있어 빌드 시간을 줄이고 관리성을 높일 수 있습니다.

특히 CI/CD 환경에서는 테스트 단계와 배포 단계를 분리하는 데 매우 유용하며, Multi-stage Build와 함께 사용하면 더욱 효율적인 Docker 운영 환경을 구축할 수 있습니다.