Next.js 14 `next build` `--distDir` 제거? 제로 다운타임 배포 5가지 함정 피하기

Next.js 14 next build --distDir 제거? 제로 다운타임 배포 5가지 함정 피하기

Next.js 14로 마이그레이션하면서 제로 다운타임 배포 방식에 예상치 못한 문제가 생겼어요. 기존에는 next build --distDir .next.new처럼 별도 디렉토리에 빌드하고 atomic swap하는 방식으로 무중단 배포를 해왔는데, 이게 안 되는 거예요.

시도와 함정

next build 명령어에서 --distDir 플래그가 사라진 걸 확인하고 당황했죠. 처음에는 Next.js 설정 파일(next.config.mjs)에서 distDir을 환경 변수로 동적으로 지정하면 되지 않을까 싶었어요.

// next.config.mjs
export default {
  distDir: process.env.NEXT_DIST_DIR || ".next",
};

이렇게 설정하고 CI/CD 파이프라인에서 NEXT_DIST_DIR=.next.new 환경 변수를 넘겨주면 될 줄 알았는데, 빌드 결과물이 여전히 .next 디렉토리에 쌓이는 거예요. --distDir 플래그가 아예 사라진 게 문제였던 거죠. 3시간 정도 이 부분에서 삽질했어요.

# 예상했던 동작 (하지만 실제로는 .next에 빌드됨)
NEXT_DIST_DIR=.next.new node node_modules/next/dist/bin/next build

원인

알고 보니 Next.js 14부터 next build 명령어 자체에서 --distDir 플래그가 완전히 제거되었더라고요. 그래서 next.config.mjs에서 distDir을 설정해도, 빌드 명령어 자체에서 이 설정을 무시하거나 제대로 반영하지 못하는 상황이었어요.

해결

결국 next build 명령어를 직접 실행하는 방식을 수정해야 했습니다. Next.js의 내부 빌드 스크립트를 직접 호출하면서 NEXT_DIST_DIR 환경 변수를 설정하는 방식으로 변경했어요.

# CI/CD 워크플로우 (.github/workflows/deploy.yml) 또는 배포 스크립트 (redeploy.sh) 수정
NEXT_DIST_DIR=.next.new node node_modules/next/dist/bin/next build

이렇게 하니 NEXT_DIST_DIR 환경 변수가 .next.new로 설정되고, Next.js 내부 빌드 스크립트가 이 환경 변수를 참조해서 원하는 디렉토리에 빌드 결과물을 생성하는 것을 확인했습니다.

결과

• 별도의 디렉토리(.next.new)에 빌드 결과물을 성공적으로 생성했습니다.
• 기존의 atomic swap 전략을 그대로 유지하여 제로 다운타임 배포를 가능하게 했습니다.
• 서비스 중단 없이 Next.js 14로의 마이그레이션을 완료했습니다.

정리 — 같은 함정 안 빠지려면

• [ ] Next.js 버전 업데이트 시, 명령어 옵션 변경 사항을 반드시 확인한다.
• [ ] --distDir과 같이 빌드 결과물 경로를 지정하는 옵션이 사라졌다면, 내부 빌드 스크립트 호출 방식을 고려한다.
• [ ] 환경 변수를 활용하여 빌드 경로를 동적으로 설정하는 방식을 염두에 둔다.
• [ ] CI/CD 파이프라인이나 배포 스크립트에서 명령어 실행 부분을 꼼꼼히 점검한다.