Next.js
Next.js 서버 렌더링에서 메타데이터가 안 나올 때
Next.js에서 서버에서만 발생하는 메타데이터 버그는 대체로 간단한데, 디버깅할 때 모든 파일을 의심하면 시간이 걸린다.
Next.js에서 서버 렌더링 시에만 메타데이터 또는 Open Graph 태그가 제대로 렌더링되지 않는 문제가 있다면, 우선 실제 HTML이 뭘 가지고 있는지 확인하는 것부터 시작해야 한다. 화면에서 보이는 문제만으로는 원인을 찾기 어렵고, 로그와 응답을 함께 봐야 다음 단계를 빠르게 좁힐 수 있다.
먼저 확인할 것: 공개 URL의 실제 HTML
로컬 개발 환경과 배포 환경에서 결과가 다를 수 있으므로, 먼저 공개된 URL에서 실제로 어떤 HTML이 전달되는지 봐야 한다. 단순히 브라우저에서 보는 것과는 다르다. 서버에서 보내주는 HTML의 <head> 태그를 직접 확인해보자.
curl -s https://example.com | grep -Ei 'title|description|canonical|og:|twitter:'
이 명령어로 보이는 것이 실제로 검색 엔진과 SNS에서 받게 되는 내용이다. 여기서 title이 있는데 og:title은 없다면, 메타데이터 함수가 제대로 실행되지 않았다는 뜻이다.
Next.js 구성과 빌드 로그 확인
문제를 좁히려면 빌드 로그를 봐야 한다. 혹시 next build 단계에서 경고나 에러가 나왔는지 확인하자. 메타데이터 함수가 동적으로 생성되는 경우, 빌드 타임에 미리 계산되는 콘텐츠와 런타임에 계산되는 콘텐츠의 차이 때문에 문제가 생길 수 있다.
npm run build
빌드 결과에서 prerendered vs on-demand ISR 같은 메시지를 보면, 어떤 페이지가 정적으로 빌드되고 어떤 것이 동적으로 생성되는지 알 수 있다.
로컬과 운영 환경의 차이
로컬에서 npm run dev로 실행했을 때는 잘 작동하는데 배포 후에는 메타데이터가 없다면, 환경 변수나 설정 파일의 차이일 가능성이 높다. 배포 환경에서만 설정되는 값들 — 예를 들어 외부 API 호출, 데이터베이스 쿼리, 또는 조건부 로직 — 이 메타데이터 함수 내에 있을 수 있다.
변경 전에, 먼저 정상 상태를 명확히 해두자. 어떤 페이지의 어떤 태그가 있어야 하는지 기록해두고, 수정 후 같은 명령어로 다시 확인해서 정말로 바뀌었는지 검증하자.
마지막: 공개 URL과 빌드 결과로 검증
수정한 후에는 세 가지를 확인하자:
- 로컬에서
npm run build후npm run start로 운영 환경처럼 실행했을 때 메타데이터가 나오는가 - curl로 그 로컬 서버에서 태그를 확인했을 때 맞는가
- 실제 배포된 URL에서도 같은 결과가 나오는가
관련된 설정이나 명령어를 작은 텍스트 파일에라도 남겨두면, 다음에 비슷한 문제가 나올 때 훨씬 빠르게 대응할 수 있다.