Next.js 정적 생성 문제를 진단할 때 먼저 볼 로그

Next.js에서 정적 생성(Static Site Generation)을 사용할 때 발생하는 문제들은 대부분 빌드 타임에 드러난다. 운영 중에는 이미 너무 늦었을 수도 있다.

따라서 빌드 로그를 자세히 읽고, 작은 이상 신호도 빨리 포착해야 한다. 무시한 경고가 나중에 큰 문제로 터질 수 있기 때문이다.

핵심 질문

정적 생성이 제대로 되고 있는가 확인해보자:

• 빌드할 때 모든 페이지가 생성되는가?
• 메타데이터가 올바르게 설정되는가?
• 외부 데이터를 제대로 가져오는가?

이 세 가지가 맞아야 한다.

먼저 제외할 원인들

정적 생성 문제라고 생각되면, 먼저 이런 것들이 아닌지 확인해보자:

• 빌드 설정이 맞는가?
• 배포 후 캐시가 올바르게 됐는가?
• 환경변수는 제대로 전달됐는가?

canonical과 메타데이터 확인

SEO를 위해 canonical 링크와 메타데이터가 중요하다. 이들이 제대로 생성되는지 확인해보자:

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

이 명령들로 실제 HTML 헤드를 확인할 수 있다.

예상되는 정상 상태 정의하기

빌드 후 어떤 파일들이 생성돼야 하는가? .next 디렉토리 구조는 어떻게 되어야 하는가? 미리 정의해두면 확인이 쉽다.

빌드 로그 읽기

빌드 출력에서 getStaticProps 실행 로그를 보자. 데이터를 제대로 가져오는가? 에러가 없는가?

비정상일 때 볼 곳

메타데이터가 빈 것 같거나, 페이지가 생성되지 않는 것 같으면, 빌드 타임 에러를 다시 확인해보자. 대부분 거기 있다.

1. 같은 조건에서 다시 빌드해본다.
2. 로그에서 경고나 에러를 정리한다.
3. 생성된 파일들을 확인한다.

정적 생성은 한 번 제대로 설정하면 매우 안정적이고 빠르다. 초기 설정에 신경을 쓸 가치가 충분하다.