Next.js 빌드 로그를 읽고 문제를 찾기

Next.js 프로젝트를 빌드할 때 로그를 대충 훑고 지나가곤 한다. 하지만 로그에는 성능 문제, 누락된 설정, 라이브러리 호환성 문제 같은 중요한 정보가 들어있다.

빌드 프로세스의 각 단계 확인하기

Next.js 빌드는 여러 단계로 나뉜다: 페이지 최적화, API 라우트 컴파일, 정적 생성 등. 각 단계의 소요 시간을 보면 병목이 어디인지 알 수 있다.

npm run build

출력에서 다음을 찾아본다:

• Page compression: 각 페이지의 빌드 결과와 크기
• Collecting page data: 정적 생성 시간
• Generating static pages: 예상보다 오래 걸리는 부분

경고 메시지 분류하기

노란색 경고는 무시해도 되는 것과 중요한 것이 섞여있다. 특히 다음을 주목해야 한다:

WARN: Detected an external image without dimensions
WARN: Resource is not listed as a dependency
WARN: Detected unused CSS

이미지 최적화 경고는 Next.js/Image 컴포넌트를 사용하면 쉽게 해결된다. 의존성 경고는 번들 크기에 영향을 미치므로 확인해야 한다.

메타데이터와 SEO 설정 확인

빌드 로그에서 메타데이터 관련 에러가 나오면 SSR 페이지의 헤드 설정을 점검해야 한다.

# 특정 페이지만 빌드해서 로그 확인
curl -s http://localhost:3000/some-page | grep -i 'og:\|twitter:\|canonical'

로컬에서 npm run build && npm start로 프로덕션 모드로 실행해본 후, 각 페이지의 메타데이터를 curl로 확인한다.

빌드 시간 최적화

빌드가 예상보다 오래 걸린다면 로그에서 단계별 시간을 비교한다.

time npm run build

만약 정적 생성 단계에서 오래 걸린다면:

• 동적 라우트의 경로가 많은지 확인
• 데이터 페칭이 병렬이 아닌 직렬로 처리되는지 확인
• ISR (Incremental Static Regeneration) 사용을 검토

환경별 빌드 비교

로컬과 CI/CD 파이프라인의 빌드 결과가 다를 수 있다. 특히 환경 변수나 Node 버전 차이 때문이다.

node --version
npm --version
# CI 환경의 로그 또는 배포 로그와 비교

빌드 로그 저장하고 비교하기

매번 빌드할 때마다 로그를 저장해두면 성능 추세를 추적할 수 있다.

npm run build 2>&1 | tee build-$(date +%Y%m%d-%H%M%S).log

이전 빌드와 비교해서 특정 페이지의 빌드 시간이 급격히 늘었는지, 새로운 경고가 생겼는지 확인한다.

체크리스트

1. 빌드 각 단계의 소요 시간을 확인한다.
2. 경고 메시지를 분류하고 중요한 것부터 해결한다.
3. 메타데이터와 SEO 설정을 검증한다.
4. 정적 생성이 병목이면 경로 수와 데이터 페칭을 최적화한다.
5. 로컬과 CI 빌드의 결과를 비교한다.
6. 빌드 로그를 저장해서 추세를 추적한다.

빌드 로그는 단순한 작업 결과가 아니라 프로젝트 상태를 나타내는 중요한 신호다.