Next.js prune으로 빌드가 막힐 때 먼저 볼 로그

문제를 너무 크게 잡지 않는다

Next.js 모노레포에서 prune 명령을 사용할 때, 문제가 생기면 마치 모든 파일이 의심스러워 보인다. 하지만 실제로는 특정 메타데이터나 빌드 설정 때문에 문제가 생기는 경우가 많다. 문제의 범위를 정확히 파악해야 해결이 빨라진다.

웹 렌더링 문제의 핵심은 한 가지 증상에만 집중하지 않는 것이다. 로컬과 운영 환경의 차이, canonical 설정, sitemap 생성을 차례대로 확인해야 원인을 찾을 수 있다.

먼저 정상 상태를 정의한다

prune 문제를 해결하려면, 먼저 정상 상태가 어떤 것인지 정해야 한다:

• 먼저 볼 값: sitemap과 RSS 피드가 제대로 생성되는가
• 함께 비교할 값: 로컬 개발 환경에서의 메타데이터
• 남겨둘 기록: 빌드 로그, HTML head, 구성 파일

실제 HTML head를 확인한다

Next.js prune이 실패하거나 빌드가 느려진다면, 생성되는 HTML의 head 태그가 올바른지 직접 확인해야 한다:

curl -s https://example.com | grep -Ei 'title|description|canonical|og:|twitter:'
npm run build

이 명령들로 실제 배포된 메타데이터와 빌드 결과를 확인할 수 있다.

Canonical 태그를 점검한다

canonical이 올바르지 않으면, prune이 제대로 동작하지 않을 수 있다. 모든 페이지에서 canonical이 명확하게 정의되어 있는지, 중복되거나 순환하는 canonical이 없는지 확인한다.

Sitemap과 RSS를 검증한다

Sitemap과 RSS 피드는 prune의 효율성에 영향을 미친다. 이 파일들이 올바른 형식으로 생성되는지, 모든 페이지를 포함하는지 확인해야 한다.

로그에서 경고를 찾는다

Next.js 빌드 로그를 자세히 보면, prune 실패의 원인이 명확하게 드러난다. 특정 페이지에서 메타데이터 생성 실패, 동적 라우팅 오류 등의 메시지를 찾는다.

단계별로 검증한다

같은 문제가 반복되는 것을 방지하려면 확인 순서를 고정한다:

1. 원래 증상이 같은 조건에서 다시 나타나는지 확인한다
2. 빌드 로그, 메타데이터, HTML head에서 바뀐 부분을 명확히 설명할 수 있는지 확인한다
3. 공개 URL, sitemap, canonical을 최종 확인한다

다음을 위해 기록한다

Next.js prune 문제를 해결한 후, 어떤 메타데이터 설정이 문제였는지, 어떻게 수정했는지 정리해두면 비슷한 문제가 생겼을 때 빠르게 대응할 수 있다.