Next.js
Next.js 메타데이터가 배포 환경에서 안 보일 때
빌드는 성공하는데 배포된 페이지의 메타데이터가 이상할 때 확인할 순서를 정리했다.
로컬에서는 잘 보이던 OG 이미지나 canonical 태그가 배포 환경에서 빠져 있으면 당황스럽다. 이럴 땐 화면만 봐서는 원인을 찾기 어렵고, 빌드 로그와 실제 HTML을 함께 확인해야 한다.
먼저 공개 URL의 HTML을 본다
배포된 페이지의 HTML 헤드를 직접 확인하는 것부터 시작한다.
curl -s https://example.com | grep -Ei 'title|description|canonical|og:|twitter:'
이 명령으로 meta 태그들이 실제로 있는지, 값이 제대로 들어가 있는지 바로 확인할 수 있다.
로컬 빌드와 비교한다
로컬에서 빌드한 결과와 배포 환경의 차이를 찾는다.
npm run build
빌드 로그를 정확히 읽어야 한다. 특히 메타데이터 생성 시점에 에러가 없었는지, 환경 변수가 제대로 설정되었는지 확인한다.
환경 변수와 빌드 타임 값 확인
Next.js에서 메타데이터 생성에 환경 변수가 필요하다면, 배포 환경에서 그 값이 실제로 전달되었는지 확인해야 한다. 예를 들어 사이트 URL, API 엔드포인트 등이 빌드 시점에 고정되는 경우가 많다.
프리렌더링 되지 않은 동적 경로인지 확인
동적 경로를 사용하는 페이지라면 generateMetadata() 함수가 제대로 설정되었는지 확인한다. 특히 데이터베이스 쿼리나 외부 API 호출이 포함되어 있다면 배포 환경의 네트워크 접근성을 점검해야 한다.
결과를 기록하고 변경은 한 가지씩만
메타데이터 문제는 재현하기 쉬워야 다음에 빨리 처리할 수 있다. 현재 페이지의 HTML 헤드를 저장해 두고, 수정할 때는 한 번에 하나씩만 바꾼다. 그래야 어느 변경이 효과가 있었는지 알 수 있다.