multi-stage build란 무엇이며 왜 사용합니까?

Question

Accepted Answer

**multi-stage build**는 하나의 Dockerfile에서 여러 `FROM` stage를 사용합니다 — 애플리케이션을 (모든 빌드 도구가 있는) 한 stage에서 빌드하고, 최종 산출물만 깨끗하고 최소한인 최종 stage로 복사합니다. 이는 **훨씬 더 작고 안전한** 프로덕션 image를 생성합니다.

## 문제: 빌드 도구가 image를 비대하게 만든다

```text
앱을 빌드하려면 빌드 도구(컴파일러, 개발 의존성, SDK)가 필요하지만,
최종 image에는 그것들이 포함되어서는 안 됨:
  → image를 비대하게 만듦(더 큰 크기, 더 느린 배포)
  → 공격 표면을 증가시킴(더 많은 소프트웨어 = 더 많은 취약점)
→ 최종 image에는 빌드된 산출물 + 그 런타임만 원함.
```

## multi-stage build

```dockerfile
# STAGE 1: "build" — 모든 빌드 도구가 있음(앱을 컴파일/번들)
FROM node:20 AS build
WORKDIR /app
COPY package*.json ./
RUN npm install              # 개발 의존성, 빌드 도구 포함
COPY . .
RUN npm run build            # /app/dist 생성

# STAGE 2: final — 빌드된 산출물만 있는 깨끗하고 최소한인 image
FROM nginx:alpine
COPY --from=build /app/dist /usr/share/nginx/html   # 빌드 출력만 복사
# → 최종 image에는 빌드 도구도, 개발 의존성도 없음 — nginx + 빌드된 파일만
```

`--from=build`는 build stage에서 최종 image로 산출물을 복사합니다. 최종 image는 **명시적으로 복사하는 것을 제외하고 build stage의 모든 것을 제외합니다** — 그래서 빌드 도구, 개발 의존성, 소스가 프로덕션에 들어가지 않습니다.

## 이점

```text
✓ 더 작은 image — 런타임 + 산출물만(종종 10배 이상 작음)
✓ 더 안전함 — 더 적은 패키지 = 더 작은 공격 표면(컴파일러/빌드 도구 없음)
✓ 더 빠른 배포/pull(더 작은 image가 더 빨리 전송됨)
✓ 하나의 Dockerfile — 빌드와 최종 image가 함께(별도의 빌드 스크립트 없음)
→ 컴파일 언어(Go, Rust, Java)와 Node/프론트엔드 빌드에 흔함.
```

## 왜 중요한가

multi-stage build를 이해하는 것은 **작고 안전한 프로덕션 image를 생성**하는 데 가치가 있으므로, 프로덕션 품질의 Docker image를 빌드하는 데 중요한 실용 지식입니다.

그것이 해결하는 문제는 실제적이고 흔합니다. 애플리케이션을 빌드하려면 **최종 프로덕션 image에 포함되어서는 안 되는** **빌드 도구**(컴파일러, SDK, 개발 의존성)가 필요합니다 — 그것들을 포함하면 image를 비대하게 만들고(더 큰 크기, 더 느린 배포 및 pull) **공격 표면**을 증가시킵니다(더 많은 설치된 소프트웨어는 더 많은 잠재적 취약점을 의미). **multi-stage build**는 여러 `FROM` stage를 사용하여 이를 우아하게 해결합니다. 모든 도구가 있는 stage에서 애플리케이션을 빌드한 다음, **최종 산출물만**(`--from=build`) 다른 모든 것을 제외하는 깨끗하고 최소한인 최종 stage로 복사합니다.

이는 **극적으로 더 작고**(종종 10배 이상 작음 — 런타임과 산출물만) **더 안전한**(악용할 빌드 도구나 불필요한 패키지 없음) image를 생성하면서, 모든 것을 단일 Dockerfile에 유지합니다(별도의 빌드 스크립트 없음).

이 패턴은 컴파일 언어(런타임에 컴파일러가 필요 없는 Go, Rust, Java)와 프론트엔드/Node 빌드(빌드 도구와 소스가 프로덕션에 필요 없는)에 표준입니다.

작고 안전한 프로덕션 image는 배포 속도, 저장소, 보안에 중요하고, multi-stage build가 이를 달성하는 표준적이고 효과적인 기법이므로(빌드 환경과 가벼운 런타임 image를 분리함), multi-stage build — 그것이 해결하는 비대함/보안 문제, 작동 방식, 이점 — 를 이해하는 것은 프로덕션 품질의 Docker image를 빌드하는 데 가치 있고 자주 적용되는 지식이며, 실세계 Dockerfile에서 널리 사용되는 모범 사례이자 효율적이고 안전한 컨테이너화 애플리케이션을 생성하는 핵심 기술입니다.