Next.js Docker Build Freezes at "creating optimized production build"

- Next.js Docker 빌드시 creating optimized production build 단계에서 멈출 때 해결법

Next.js를 Docker 환경에서 빌드하다 보면, creating optimized production build 단계에서 무한정 멈추는 상황을 겪는 분들이 많습니다. 겉보기에는 빌드가 진행 중인 것처럼 보이지만 사실은 내부적으로 에러가 발생했음에도 불구하고 멈춰 있는 상태입니다. 저 역시 이 문제 때문에 시간을 꽤 허비했습니다. 원인을 파악하고 나니 의외로 단순한 의존성 문제였습니다. 이번 글에서는 제가 직접 겪었던 문제 상황과 해결 방법을 정리해 보겠습니다.

해결 방법

결론부터 말하자면 운영체제에 따라 다른 의존성 문제입니다.

그래서 node_modules폴더와 package-lock.json을 지우고 빌드하면 해결됩니다.

도커파일에서도 package.json만 가지고 의존성을 설치해야 합니다.

이런 식으로 말입니다.

ARG NODE_VERSION=20-alpine

FROM node:${NODE_VERSION} AS deps

RUN apk add --no-cache libc6-compat

WORKDIR /app

COPY package.json ./

RUN npm i

FROM node:${NODE_VERSION} AS build

WORKDIR /app

COPY --from=deps /app/node_modules ./node_modules

COPY . .

RUN npm run build

FROM node:${NODE_VERSION} AS prod-deps

ENV NODE_ENV=production

WORKDIR /app

COPY --from=deps /app/package*.json ./

RUN npm ci --omit=dev

문제 원인

Next.js 15버전 이후로는 next build 커맨드에 --turbopack 플래그를 달아서 빌드하는 방법이 일반적일 겁니다. 그런데 --turbopack 플래그를 달면 의존성 관련 에러를 던지지 않아서 삽질하기 딱 좋습니다. 실제로는 에러를 던지면서 끝나야 하는데 그러지 않기 때문에 빌드가 계속 진행되고 있는 것처럼 보이는 겁니다.

시험삼아 --turbopack 플래그 없이 next build로 빌드해보면 이렇게 에러가 나옵니다. 여기서 문제 원인에 대한 실마리를 찾을 수 있었습니다.

@tailwindcss/oxide-linux-x64-musl 모듈을 찾을 수 없다고 나오네요.

제 개발 환경은 Windows였고 빌드 환경은 Ubuntu입니다. package-lock.json을 확인해 보면 개발 환경에 깔려 있는 tailwindcss 의존성을 확인할 수 있습니다.

제 개발 환경 Windows에서는 @tailwindcss/oxide-win32-x64-msvc 의존성이 깔려 있습니다. 그렇기 때문에 package-lock.json을 가져가서 의존성을 설치하면 이것이 그대로 깔리게 됩니다. 하지만 빌드 환경 Ubuntu에서 코드를 실행할 때는 운영체제에 맞는 @tailwindcss/oxide-linux-x64-musl 의존성을 찾기 때문에 에러가 발생하는 것이죠.

이렇게 운영체제에 따라 달라지는 의존성은 package-lock.json에 등록되지 않은 상태에서는 npm install을 할 때 자동으로 실행한 환경에 맞게끔 설치가 됩니다. 따라서 빌드 환경에서는 package-lock.json없이 빌드함으로써 빌드 환경에 맞는 의존성을 설치하게끔 했습니다.

맺음말

정리하자면, Next.js Docker 빌드가 creating optimized production build 단계에서 멈추는 주된 이유는 운영체제별 의존성 차이 때문이었습니다. package-lock.json을 그대로 사용하기보다는, 도커 빌드 환경에서 npm install을 통해 해당 OS에 맞는 의존성을 새로 설치하도록 하는 방식이 가장 확실한 해결책이었죠.

이 문제는 Next.js 15 이후 --turbopack 옵션 사용 시 에러가 표시되지 않아 삽질하기 좋은 함정이기도 합니다. 혹시 같은 문제를 겪고 있다면, 위 방법을 적용해 보시길 추천드립니다. 불필요한 빌드 에러로 시간을 낭비하지 않고, 안정적으로 배포 환경을 세팅할 수 있으실 겁니다.