Next.js Standalone 모드 도입을 통한 이미지 크기 80% 최적화

How I Shrank a Next.js Image by 80% in My First Week of Docker

Tazoh Yanick2026년 6월 4일7분intermediate

AI 요약

Context

Next.js 기반 AI 서비스의 Docker 이미지 생성 시 불필요한 build artifacts와 runtime 의존성이 포함되어 1.37GB의 거대 이미지 생성. npm ci --omit=dev 적용 후에도 Next.js 런타임 필수 패키지가 devDependencies로 분류되어 이미지 크기가 줄어들지 않는 병목 현상 발생.

Technical Solution

next.config.ts 내 output: "standalone" 설정으로 런타임에 필요한 최소 파일만 추적하여 .next/standalone 폴더로 번들링
Multi-stage build 구조를 설계하여 빌드 단계의 무거운 도구들을 배제하고 실행 단계에서는 standalone 결과물과 static 파일만 복사
docker history 명령어를 통한 레이어별 용량 분석으로 node_modules와 .next 디렉토리의 낭비 요소 식별 및 제거
ENV HOSTNAME=0.0.0.0 설정을 통해 Standalone 모드의 기본 localhost 바인딩 문제를 해결하고 Docker 포트 매핑 활성화
Docker Compose의 depends_on 내 condition: service_healthy 설정을 적용하여 DB 준비 상태 확인 후 API가 기동되는 Readiness-based Orchestration 구현

Impact

이미지 크기: 1.37GB에서 269MB로 감소 (약 80% 최적화)
Docker Hub 압축 크기: 64.6MB까지 축소
배포 효율성: 이미지 크기 감소에 따른 네트워크 전송 및 풀링 시간 5배 단축

실천 포인트

- Next.js 프로젝트 Docker화 시 `output: standalone` 설정 적용 여부 검토 - `docker history`를 통해 실제 용량 점유 레이어를 확인하는 데이터 기반 최적화 습관화 - Multi-stage build를 통해 빌드 타임 의존성과 런타임 의존성을 엄격히 분리 - 컨테이너 간 의존성 정의 시 단순 순서(Order)가 아닌 상태(Healthcheck) 기반 기동 설계 적용 - 기본 bridge 네트워크 대신 Custom Network를 생성하여 자동 DNS resolution 활용

태그

#Docker #Multi-Stage Build #Container Optimization #Next.js #SRE

원문 읽기