Docker 멀티스테이지 빌드로 Next.js 이미지 1.2GB → 180MB

Next.js 앱을 순진하게 도커라이즈하면 1GB가 우습게 넘는다. node_modules와 빌드 도구가 전부 실려 있기 때문이다. 멀티스테이지 빌드와 standalone 출력으로 180MB까지 줄인 과정을 기록한다.

핵심 1 — output: "standalone"

// next.config.ts
const nextConfig = {
  output: "standalone",
};

이 옵션을 켜면 빌드 시 .next/standalone에 실행에 필요한 파일과 node_modules의 사용분만 트레이싱해서 복사해 준다. 전체 node_modules를 실을 필요가 없어진다.

핵심 2 — 스테이지 분리

FROM node:22-alpine AS deps
WORKDIR /app
COPY package*.json ./
RUN npm ci

FROM node:22-alpine AS builder
WORKDIR /app
COPY --from=deps /app/node_modules ./node_modules
COPY . .
RUN npm run build

FROM node:22-alpine AS runner
WORKDIR /app
ENV NODE_ENV=production
COPY --from=builder /app/.next/standalone ./
COPY --from=builder /app/.next/static ./.next/static
COPY --from=builder /app/public ./public
EXPOSE 3000
CMD ["node", "server.js"]

runner 스테이지에는 빌드 도구도, devDependencies도, 소스 코드도 없다. standalone 산출물과 정적 파일뿐이다.

덤 — 캐시 순서

package*.json 복사와 npm ci를 소스 복사보다 앞에 두는 게 레이어 캐시의 핵심이다. 코드만 바뀌면 의존성 레이어는 재사용된다. CI에서 buildx의 --cache-from까지 붙이면 재빌드가 1분 안쪽으로 들어온다.

결과: 1.2GB → 180MB, 콜드 풀 시간 4분의 1, ECS 배포 롤링 속도 체감 2배. 옵션 하나와 Dockerfile 구조만으로 얻는 이득치고는 크다.