배포 빌드가 오래 걸릴 때 첫 확인

프로젝트가 커지면서 배포 빌드 시간이 길어졌다. 로컬에서는 30초인데 CI 파이프라인에서는 5분 이상 걸린다. 이럴 때 대부분 캐시 설정을 놓친다.

먼저 할 일: 캐시 확인

CI 환경은 매번 깨끗한 상태에서 시작되기 쉽다. 로컬에서는 node_modules가 계속 유지되지만, 파이프라인은 매 빌드마다 의존성을 다시 받는다.

npm run build

기본 빌드 명령만으로는 캐시 상황을 알 수 없다. CI 로그를 보면 npm install 단계가 얼마나 오래 걸리는지 확인해야 한다.

캐시 레이어 추가하기

Docker나 GitHub Actions를 쓴다면 이전 빌드의 node_modules를 재사용할 수 있다. 의존성 파일(package-lock.json)이 바뀌지 않았다면 굳이 다시 받을 필요가 없다는 뜻이다.

GitHub Actions라면:

• actions/setup-node의 cache 옵션으로 npm 캐시 활성화
• Docker라면 멀티스테이지 빌드에서 RUN npm ci --prefer-offline 같은 최적화 옵션 사용

빌드 결과 확인하기

캐시를 설정했으면 CI 로그에서 다음을 확인한다:

1. npm install 단계가 "캐시 히트" 상태인지 확인
2. 번들 크기가 예상보다 커지지 않았는지 확인 (npm run build 출력이나 .next/static 디렉토리 크기)
3. 빌드 중 경고나 에러가 없는지 확인

로컬과 운영 환경 비교

로컬에서는 빠르지만 배포 환경에서 느린 경우, 대부분 환경 변수나 빌드 플래그 차이다. 로컬에서 NODE_ENV=production npm run build로 실제 배포 환경처럼 테스트해보자.

실제로 프로덕션 모드에서는 트리셰이킹, 최소화, 소스맵 생성 같은 처리가 추가되어 훨씬 오래 걸린다. 그게 정상이다.

기억할 점

빌드 시간이 길어졌다면 캐시 설정을 먼저 확인하고, 그 다음 환경 변수와 빌드 플래그를 비교하는 순서가 효율적이다. 작은 확인들이 쌓이면 다음 번에 비슷한 문제가 나올 때 훨씬 빨리 찾을 수 있다.