Docker 빌드 속도 및 이미지 용량 폭발 해결: Multi-stage Build 아키텍처

10월 02, 2026

[Troubleshooting] Docker 빌드 시간 및 이미지 용량 폭발 해결: Multi-stage Build 아키텍처

"Node.js 백엔드 앱을 도커(Docker)로 말아서 ECR에 올리는데, 이미지 용량이 무려 2GB를 넘어갑니다. 게다가 GitHub Actions에서 빌드할 때마다 npm install을 처음부터 다시 도느라 CI/CD 배포 파이프라인이 10분이나 걸립니다."

클라우드 네이티브 환경을 구축하는 개발 조직이 컨테이너화를 시작할 때 필연적으로 겪게 되는 생산성 붕괴의 늪입니다. 뚱뚱한 도커 이미지는 레지스트리 보관 비용을 높일 뿐만 아니라, 서버가 스케일 아웃(Scale-out)될 때 이미지를 다운받는 속도까지 저하시켜 서비스 장애 복구를 극도로 지연시킵니다.

초보자들은 이 문제를 해결하기 위해 .dockerignore 파일에 모듈 폴더를 추가하는 1차원적인 방법에만 머뭅니다. 본 가이드에서는 불필요한 빌드 도구들을 도커 이미지에서 완벽하게 적출해 내는 멀티 스테이지 빌드(Multi-stage Build) 아키텍처와, 캐시 마운트를 통한 빌드 시간 10배 단축 노하우를 단호하게 제시합니다.

📌 이 글의 핵심 포인트

비대화의 본질: 실행에는 전혀 필요 없는 컴파일러와 소스코드까지 프로덕션 이미지에 포함되는 구조적 결함

Multi-stage Build: 빌드 환경(Builder)과 실행 환경(Runner)을 분리하여 껍데기만 추출하는 레이어 다이어트 기법

레이어 캐싱(Layer Caching) 최적화: package.json을 먼저 복사하여 의존성 다운로드 병목을 완벽 방어하는 전략

1단계: 핵심 원인 분석 - 왜 이미지는 2GB 괴물이 되는가?

기본적인 Dockerfile을 작성할 때 FROM node:18 처럼 무거운 베이스 이미지를 그대로 사용하는 것이 비극의 시작입니다. 이 안에는 소스코드를 자바스크립트로 변환하는 데 필요한 각종 빌드 도구, 파이썬, C++ 컴파일러가 모두 들어있습니다.

애플리케이션이 빌드되고 나면, 프로덕션 서버에서 이 컴파일러들은 쓰레기 데이터일 뿐입니다. 하지만 기존 방식으로는 이 쓰레기들을 그대로 끌어안은 채 이미지가 구워지기 때문에 용량이 기하급수적으로 팽창합니다.

2단계: 완벽한 트러블슈팅 1 - 레이어 캐싱 분리

도커는 위에서부터 아래로 층(Layer)을 쌓으며 빌드합니다. 코드가 한 줄이라도 바뀌면 그 아래의 모든 층은 캐시가 깨져 다시 실행됩니다.


# ❌ 최악의 안티 패턴: 소스코드를 통째로 복사한 뒤 npm install 실행
# 소스코드가 1줄만 바뀌어도 npm install을 처음부터 다시 실행함
COPY . /app
RUN npm install

# ✅ 무결점 아키텍처: 패키지 파일만 먼저 복사하여 캐시 완벽 분리
# package.json이 안 바뀌면 npm install 과정을 건너뜀 (빌드 시간 5분 단축)
COPY package.json package-lock.json ./
RUN npm ci
COPY . .

이 사소한 순서 변경 하나가 깃허브 액션(GitHub Actions)의 CI/CD 빌드 시간을 10분에서 1분으로 압축시킵니다.

3단계: 엔터프라이즈 아키텍처 - Multi-stage Build

빌드 속도를 높였다면 이제 용량을 쥐어짤 차례입니다. Dockerfile 안에 FROM 지시어를 두 번 사용하여, 첫 번째 단계(빌더)에서 코드를 컴파일하고 두 번째 단계(러너)에는 오직 실행에 필요한 가벼운 산출물만 넘겨주는 아키텍처를 적용합니다.


# --- 1단계: Builder 환경 (여기서 온갖 무거운 짓을 다 합니다) ---
FROM node:18 AS builder
WORKDIR /app
COPY package.json package-lock.json ./
RUN npm ci
COPY . .
RUN npm run build  # 타입스크립트를 JS로 빌드

# --- 2단계: Production 환경 (가벼운 Alpine 베이스 이미지를 사용합니다) ---
FROM node:18-alpine AS runner
WORKDIR /app

# 1단계(builder)에서 생성된 핵심 산출물(dist)만 가져옵니다!
# 무거운 원본 소스코드와 컴파일러들은 전부 버려집니다.
COPY --from=builder /app/dist ./dist
COPY --from=builder /app/package.json ./package.json

# 프로덕션 실행에 필요한 모듈만 가볍게 설치
RUN npm install --only=production

CMD ["node", "dist/main.js"]

이 멀티 스테이지 빌드 아키텍처를 통과하면, 2GB짜리 괴물 이미지는 100MB 수준의 깃털처럼 가벼운 컨테이너로 완벽하게 다이어트합니다.

🙋‍♂️ 자주 묻는 질문 (FAQ)

Q. Alpine 이미지 적용 시 C++ 관련 에러가 뜹니다. 왜 그런가요?
A. Alpine 리눅스는 극도의 경량화를 위해 표준 C 라이브러리(glibc) 대신 musl libc를 사용합니다. 이미지 처리나 암호화 패키지(예: bcrypt, sharp) 중 일부가 이에 호환되지 않아 컴파일 에러를 뱉을 수 있습니다. 이때는 node:18-slim 이미지를 대안으로 사용하는 것이 좋습니다.

💡 핵심 정리 및 마무리

컨테이너 빌드는 단순히 코드를 압축하는 과정이 아닙니다. 애플리케이션의 불순물을 걸러내고 순수한 본질(Executable)만 추출하는 정교한 연금술입니다. Docker의 레이어 캐싱 원리와 멀티 스테이지 빌드의 철학을 인프라에 주입하여, 빠르고 날렵하며 보안성까지 완벽한 클라우드 네이티브 배포 파이프라인을 완성하시기 바랍니다.

이 블로그 검색

HAGOCUBE | 디지털 생산성 아키텍트