hohyeon.dev2026. 9. 11.73

카카오톡에 링크를 보냈더니 미리보기가 비어 있던 것을 파일 하나로 고친 방법

#Engineering Note
#Next.js
#SEO

문제 발생

사이트 주소를 카카오톡으로 보냈더니 미리보기에 제목만 덜렁 있고 그림도 설명도 없었습니다. 슬랙과 X에서도 마찬가지였습니다. 페이지 자체는 멀쩡했습니다.

응답 HTML을 보니 이유가 그대로 있었습니다 — og:image가 없고, og:description은 서비스 소개가 아니라 예전에 적어 둔 긴 문장이었습니다.

원인 분석

미리보기는 페이지를 렌더하지 않고 메타 태그만 읽습니다. Open Graph 프로토콜은 og:title, og:type, og:image, og:url을 기본 속성으로 정하고, 메신저의 스크래퍼는 그 태그를 읽어 카드를 만듭니다. og:image가 없으면 그림이 없고, og:description이 없으면 설명이 없습니다. 카카오 개발자 문서도 서비스 서버의 방화벽이 카카오 스크랩 서버를 막으면 이미지가 느리거나 표시되지 않을 수 있다고 적어 둡니다 — 즉 카카오 쪽 서버가 우리 페이지를 직접 긁어 갑니다.

Next.js는 이 태그를 파일 규칙으로 만들어 줍니다. 문서에 따르면 opengraph-image와 twitter-image 파일 규칙은 라우트 세그먼트의 Open Graph·Twitter 이미지를 정하고, 사용자가 링크를 공유할 때 소셜 네트워크와 메시징 앱에 보이는 이미지를 설정하는 데 쓰입니다. 방법은 둘입니다 — 이미지 파일(.jpg, .png, .gif)을 두거나, 코드로 만들거나.

해결 방안

app/opengraph-image.png를 둡니다. 그 세그먼트와 아래 라우트의 <head>에 og:image 태그가 생깁니다. 대체 텍스트는 같은 이름의 opengraph-image.alt.txt에 한 줄로 적습니다.

app/
  layout.tsx
  opengraph-image.png
  opengraph-image.alt.txt

그림은 빌드 밖에서 한 번 만들어 커밋합니다. 코드로 만드는 방식은 요청마다 그리거나 런타임에 글꼴을 받아야 합니다. 워드마크와 한 줄 설명뿐인 그림이라면 SVG에서 한 번 PNG로 변환해 저장소에 넣는 것이 단순하고, 배포 이미지에 이미지 처리 라이브러리가 없어도 됩니다.
설명은 metadata가 맡습니다. 루트 layout의 description이 og:description으로도 나갑니다. 미리보기에 맞는 두 문장 정도로 다시 씁니다. 카드에서는 앞 몇십 글자만 보이므로 핵심이 앞에 와야 합니다.
트위터 카드 종류를 정합니다. twitter.card를 summary_large_image로 두면 X가 큰 그림 카드를 씁니다. 별도 twitter-image 파일이 없으면 OG 이미지를 그대로 씁니다.
렌더된 HTML로 확인합니다. curl -s https://example.com | grep -o '<meta property="og:[^>]*>'로 태그 네 개가 나오는지 봅니다. 그다음 실제로 메신저에 보내 봅니다.
이미 한 번 긁어 간 주소는 캐시가 남습니다. 카카오는 스크랩 결과를 한동안 저장하므로 고친 뒤에도 옛 카드가 보일 수 있습니다. 카카오 개발자 사이트의 캐시 초기화 도구(tool/clear/og)로 그 주소의 스크랩 정보를 비웁니다. 서브도메인은 주소가 다르므로 각각 처리합니다.

공식 문서

마지막 수정 2026. 9. 11.

아직 댓글이 없어요. 첫 의견을 편하게 남겨 보세요.