Next.js에서 서버에서만 터지는 문제를 디버깅하기

Next.js는 클라이언트 사이드와 서버 사이드 코드를 함께 실행한다. 로컬 개발 중에는 감지 못 했던 버그가 배포 후 서버 렌더링 과정에서 드러날 수 있다.

현재 상황 파악

서버에서만 터지는 문제가 무엇인지 파악한다:

• 빌드 시점에서 에러가 나는가? (정적 생성)
• 요청 시점에서 에러가 나는가? (서버 사이드 렌더링)
• 특정 경로에서만 문제가 생기는가?

HTML head 확인

배포된 페이지의 메타 정보를 확인한다:

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

HTML head에 필요한 메타 태그가 모두 있는지 본다. 서버 렌더링이 제대로 되지 않으면, og:image나 title 같은 태그가 없을 수 있다.

빌드 로그 확인

빌드 과정에서 발생한 경고나 에러를 본다:

npm run build

빌드 로그에서 "error", "warning", "failed" 같은 키워드를 찾는다. 특히 동적 경로나 정적 생성 과정에서 실패했다면 그 부분을 집중적으로 살펴본다.

Metadata와 canonical 태그 검토

Next.js의 메타데이터 생성 로직을 확인한다:

// 로컬에서만 완벽하지만, 배포 후 실패하는 경우
export const metadata = {
  title: '페이지 제목',
  description: '페이지 설명',
  openGraph: {
    url: 'https://example.com/page',
  },
};

URL을 하드코딩했다면, 배포 환경의 도메인과 다를 수 있다. 환경변수를 사용하는 것이 안전하다.

Sitemap과 RSS 확인

SEO를 위한 정적 파일들이 제대로 생성되는지 확인한다:

npm run build
ls -la .next/  # 생성된 정적 파일 확인

동적으로 생성되는 sitemap이나 RSS feed가 있다면, 빌드 시점에 올바른 데이터를 받는지 확인한다. API 호출이 실패하면 생성도 실패한다.

작게 바꿔볼 것들

OSS 호환성이나 서버 전용 라이브러리 때문일 수 있다:

• window 객체 참조: 서버에서는 없으므로 주의
• 외부 라이브러리: 브라우저 전용인지 확인
• 환경변수: 런타임 vs 빌드타임

// 서버에서 실패
const windowWidth = window.innerWidth;  // 에러

// 안전한 방법
const windowWidth = typeof window !== 'undefined' ? window.innerWidth : 0;

단계별 검증

1. 증상을 정확히 재현한다. 어떤 경로에서, 어떤 에러 메시지가 나오는가?
2. 로그와 응답에서 바뀐 부분을 한 줄로 설명한다. 예를 들어 "메타데이터 생성 중 undefined 참조"라고.
3. 로컬 개발 서버와 프로덕션 빌드 결과를 비교한다.

마무리

결과가 바뀐 이유를 로그와 응답으로 설명할 수 있으면 충분히 정리된 것이다. 이를 기록해두면 다음 배포 때 같은 실수를 반복하지 않을 수 있다.