Next.js metadataBase를 지정하지 않아 OG 이미지가 빠졌던 설정 노트

증상이 보인 위치부터 달랐다

배포한 Next.js 페이지를 메신저에 붙여 넣었는데 제목은 나오고 이미지가 비어 있었다. 브라우저에서 페이지를 여는 데는 문제가 없어서 처음에는 이미지 파일이나 CDN을 의심했다. curl로 HTML의 Open Graph 태그를 확인하니 og:image 값이 상대 경로처럼 생성되어 있었다.

기준 URL을 명시했다

app/layout.tsx의 metadata에 사이트의 실제 주소를 기준으로 넣었다. 개발 환경 주소를 그대로 넣지 않도록 환경 변수는 배포 단계에서 주입했다.

import type { Metadata } from 'next'
export const metadata: Metadata = {
  metadataBase: new URL(process.env.NEXT_PUBLIC_SITE_URL ?? 'http://localhost:3000'),
  openGraph: { type: 'website', siteName: '투린의 기록', images: ['/og/default.png'] },
}

public/og/default.png의 파일 위치와 메타데이터에 쓰는 URL이 헷갈렸다. public 아래 파일은 URL에서 /og/default.png로 접근한다.

배포 전에 확인한 명령어

curl -sL https://example.com/notes | grep -E 'og:image|twitter:image|canonical'

확인 기준은 이미지 URL이 https로 시작하는지, 200과 이미지 Content-Type을 반환하는지, canonical과 Open Graph URL이 운영 도메인인지였다.

고정한 체크리스트

• metadataBase가 운영 주소를 가리킨다.
• URL 앞에 /public을 붙이지 않았다.
• 소셜 미리보기 캐시를 고려한 파일명 기준이 있다.

페이지가 보인다는 것과 공유 카드가 완성됐다는 것은 별개의 검사 대상이었다. 다음부터는 HTML 메타 태그와 이미지 응답을 함께 확인한다.