Next.js 서버에서만 오류가 날 때 로그 읽기

로컬 개발 환경과 운영 Next.js 서버는 동작 방식이 완전히 다르다. 개발 서버는 파일 변경을 감지해서 핫 리로드하고, 운영 서버는 빌드된 정적 산물을 서빙한다. 데이터 페칭도 로컬에서는 빠르지만 운영에서는 지연될 수 있다. 이런 차이 때문에 서버에서만 오류가 난다.

문제의 경계 정하기

모든 페이지에서 오류가 나는지, 특정 페이지에서만 나는지, 특정 시간대에만 나는지 파악한다. 각각의 원인이 다르다.

로컬과 운영 비교

로컬에서는 캐시가 없고, 운영에서는 매우 공격적으로 캐싱될 수 있다. sitemap과 RSS도 빌드 시점에 생성되기 때문에 로컬에서는 동적으로, 운영에서는 정적으로 제공될 수 있다.

• 확인할 것: Sitemap/RSS 생성 여부, 빌드 로그, 메타데이터
• 비교 기준: 정상일 때의 빌드 결과
• 기록할 것: 빌드 시간, 생성된 파일 목록, 에러 메시지

canonical 링크와 설정 확인

캐노니컬 링크, og:url 등이 정확히 생성되는지 확인한다. 이들이 잘못되면 사용자가 중복 페이지로 유입될 수 있다.

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

응답 확인

서버가 반환하는 HTTP 상태 코드, 응답 헤더, 응답 바디가 모두 정상인지 확인한다.

빌드 로그 분석

Next.js 빌드 시 경고나 에러가 있었는지 확인한다. 빌드는 성공했지만 런타임에 실패하는 경우도 있기 때문이다.

위험한 수정 피하기

성능이나 캐시 정책을 강화했다고 기능이 제거되면 안 된다. 각 변경의 부작용을 함께 확인한다.

체크리스트

1. 재현 조건: 서버에서 오류가 나는 정확한 상황
2. 로그: 빌드 로그, 런타임 에러
3. 설정: 환경 변수, 배포 URL, 캐시 정책

완료 기준

1. 오류의 정확한 지점을 로그에서 찾을 수 있는가
2. 로컬에서는 정상인 이유를 설명할 수 있는가
3. 운영에서 동일하게 재현 가능한가

서버 오류는 사용자에게 직접 영향을 주기 때문에, 빌드 단계부터 운영까지 모든 과정을 면밀히 검토해야 한다.