Next.js OG 이미지가 안 보일 땐 어디를 확인할까

SNS 공유할 때 OG 이미지가 나오지 않으면 답답하다. 하지만 화면에서 아무것도 모르니까 원인을 찾기가 어렵다. 이런 경우 서버 환경을 먼저 확인하는 게 핵심이다.

OG 이미지가 작동하려면

Next.js에서 이미지를 제공하려면:

• 메타 태그가 올바르게 설정돼 있어야 함
• 서버에서 이미지 파일에 접근 가능해야 함
• 이미지 경로가 절대 경로여야 함 (상대 경로는 안 됨)

메타 태그 확인 (서버에서)

브라우저에서 렌더링된 HTML을 보는 것만으로는 부족하다. 실제 서버가 전송하는 HTML을 확인해야 한다.

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

이 curl 결과에서 og:image 태그가 있는가? URL이 올바른가?

이미지 URL이 정말 접근 가능한가?

OG 이미지 URL이 브라우저에서 직접 열렸을 때 이미지가 보이는지 확인한다. 404면 당연히 SNS에서도 안 보인다.

// metadata.ts 또는 getServerSideProps에서
export const metadata = {
  openGraph: {
    images: [
      {
        url: 'https://example.com/og-image.png',  // 반드시 전체 URL
        width: 1200,
        height: 630,
      },
    ],
  },
};

URL 앞에 도메인이 빠지거나, /public 폴더 경로를 그대로 썼으면 안 된다.

동적 이미지 생성의 경우

파라미터에 따라 다른 이미지를 생성한다면, 그 엔드포인트가 정말 이미지를 반환하는지 확인해야 한다.

curl -i https://example.com/api/og?title=test

Content-Type이 image/png 또는 image/jpeg인가? HTTP 상태가 200인가?

환경변수 때문일 수도

Staging과 Production에서 이미지 URL이 다를 수 있다. 로컬 개발 환경에서는 localhost 주소를 쓰지만, 배포 후엔 실제 도메인을 써야 한다.

.env.production에서 NEXT_PUBLIC_ 변수들을 확인하자. OG 이미지 URL에 환경변수를 포함시켜야 한다면, 빌드 타임에 제대로 주입됐는가?

캐시 문제 (SNS 크롤러)

SNS 플랫폼들은 OG 이미지를 캐시한다. 이미지를 고쳤어도 SNS가 이전 캐시를 계속 사용할 수 있다.

• Twitter: twitter.com/search?q=url:your-url로 검색해서 새로고침 버튼 찾기
• Facebook: developers.facebook.com의 디버거로 다시 크롤링 요청
• LinkedIn: URL 직접 공유한 후 다시 캐시 초기화

배포 후 한 번 더 확인

빌드 후엔 반드시 실제 배포 URL에서 curl로 메타 태그를 재확인한다. 로컬과 다를 수 있기 때문이다.