Docker 멀티스테이지 빌드 실전 - Node.js·Next.js 이미지 크기 줄이는 체크리스트

Dockerfile - Node.js API 서버 멀티스테이지 기본
# 1단계: 의존성 설치 (devDependencies 포함)
FROM node:22-alpine AS deps
WORKDIR /app
COPY package*.json ./
RUN npm ci

# 2단계: 빌드 (TypeScript 컴파일 등)
FROM node:22-alpine AS builder
WORKDIR /app
COPY --from=deps /app/node_modules ./node_modules
COPY . .
RUN npm run build

# 3단계: 런타임 (프로덕션 의존성만)
FROM node:22-alpine AS runner
WORKDIR /app
ENV NODE_ENV=production

COPY package*.json ./
RUN npm ci --omit=dev  # devDependencies 제외

COPY --from=builder /app/dist ./dist

EXPOSE 3000
CMD ["node", "dist/index.js"]

next.config.js - standalone 출력 설정
/** @type {import('next').NextConfig} */
const nextConfig = {
  output: 'standalone',
  // ...다른 설정
};

module.exports = nextConfig;

Dockerfile - Next.js standalone 멀티스테이지
# 1단계: 의존성 설치
FROM node:22-alpine AS deps
WORKDIR /app
COPY package*.json ./
RUN npm ci

# 2단계: Next.js 빌드
FROM node:22-alpine AS builder
WORKDIR /app
COPY --from=deps /app/node_modules ./node_modules
COPY . .
RUN npm run build

# 3단계: 런타임 (standalone 결과물만 복사)
FROM node:22-alpine AS runner
WORKDIR /app
ENV NODE_ENV=production

# standalone 폴더 전체 복사
COPY --from=builder /app/.next/standalone ./
# 정적 자산 복사 (standalone에 포함되지 않음)
COPY --from=builder /app/.next/static ./.next/static
COPY --from=builder /app/public ./public

EXPOSE 3000
ENV PORT=3000
ENV HOSTNAME="0.0.0.0"
CMD ["node", "server.js"]

이미지 크기 확인 및 레이어 분석
# 이미지 크기 확인
docker images my-app

# 레이어별 크기 분석 (dive 설치 필요)
dive my-app

# docker history로 레이어 크기 확인
docker history my-app --no-trunc

# 빌드 시 단계별 크기 출력
docker build --progress=plain -t my-app .

멀티스테이지 빌드 체크리스트 - 한 번에 검증
# 빌드
docker build -t my-app:test .

# 이미지 크기 확인
docker images my-app:test

# 컨테이너 실행 후 헬스 체크
docker run -d -p 3000:3000 --name my-app-test my-app:test
curl http://localhost:3000/health

# 컨테이너 파일 구조 확인 (불필요 파일 잔류 체크)
docker exec my-app-test ls -la /app

# 정리
docker stop my-app-test && docker rm my-app-test

.dockerignore - 기본 설정
node_modules
.git
.gitignore
.env
.env.local
.env.*.local
.next
dist
coverage
*.log
.DS_Store
README.md