Next.js 서버 렌더링 문제 빠르게 좁히기

웹이 안 나올 때 화면만 보고 판단하면 문제의 원인이 어디 있는지 놓치기 쉽다. 네트워크, HTML 렌더링, 메타데이터, 라우팅 중 어디가 문제인지 알아야 다음 수정이 빠르다.

문제를 체계적으로 추적하려면 먼저 현재 상태를 기록해두는 게 중요하다. 같은 증상이 또 나왔을 때 이 기록이 있으면 원인 추적이 훨씬 빨라진다.

먼저 확인할 것: 메타데이터 출력

curl로 HTML 응답을 받아서 메타데이터를 확인하는 게 가장 빠르다.

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

html 문서의 head 섹션에 필요한 메타 정보가 있는지 그 자리에서 확인할 수 있다. 브라우저의 검사 도구를 켜서 하나씩 확인하는 것보다 훨씬 빠르다.

로컬과 운영 상태 비교하기

로컬에서는 잘 동작하는데 운영에서 문제가 생기는 경우가 자주 있다. 로컬과 운영의 환경 차이를 놓치면 같은 실수를 반복하게 된다.

• 빌드 방식 (로컬은 dev, 운영은 production)
• 환경 변수 값
• 배포된 코드의 버전

빌드 후 확인하는 순서

수정한 후에는 먼저 빌드를 다시 한다.

npm run build

빌드 로그에 경고나 에러가 있는지 확인한다. 그 다음 실제 응답 코드를 본다.

curl -i https://example.com

HTTP 상태 코드가 200인지, 응답이 정상인지 한 번에 확인할 수 있다.

작은 변경부터 테스트하기

한 번에 여러 설정을 바꾸면 어느 것이 문제를 일으켰는지 알기 어렵다. 항상 한 가지 항목을 수정하고, 결과를 확인하고, 다음 항목으로 넘어가는 식으로 진행한다.

1. 수정
2. 빌드
3. 현재 상태 기록
4. 공개 URL에서 직접 확인

이 과정을 반복하면서 어디가 정상이고 어디가 문제인지 분명히 해둔다. 남겨진 기록이 있으면 다음 번 유사 문제를 훨씬 빨리 처리할 수 있다.