개발 slecs

환경별로 다른 OG URL, 환경 변수로 통일

목차

src/app/layout.tsx 에서 소셜 미디어 공유용 Open Graph 메타데이터를 환경 변수 기반으로 수정하고 metadataBase를 추가했다. 작은 수정처럼 보이지만, 개발/스테이징/프로덕션 환경을 분리해서 운영하는 팀이라면 꽤 자주 마주치는 함정이다.

OG 메타데이터와 하드코딩의 함정

Open Graph(OG) 메타데이터는 페이지 링크를 카톡, 인스타그램, 슬랙 같은 채널에 공유할 때 미리보기 썸네일과 제목, 설명으로 나타나는 데이터다. og:url, og:title, og:image 같은 메타 태그들이 그것이다. 문제는 이 정보가 어느 환경에서 페이지를 열었는지에 따라 달라져야 한다는 점인데, 코드에 도메인을 직접 박아 놓으면 개발/스테이징/프로덕션 어디서나 같은 URL이 공유된다.

예를 들어 개발 환경에서 테스트 중 공유 버튼을 누르면 실제로는 dev-own1second.com 으로 공유되어야 하는데, 코드에 own1second.com 이 박혀 있으면 사용자들이 프로덕션 페이지로 자동 리다이렉트된다. 반대로 스테이징에서 테스트할 때도 본서비스 URL이 노출되는 식이다. 이렇게 되면 OG 미리보기가 정확하지 않을 뿐 아니라, SNS에 잘못된 버전이 캐시되면 되돌리기가 까다롭다.

해결책: NEXT_PUBLIC_APP_URL 과 metadataBase

Next.js 13+ App Router 는 layout.tsx 에서 metadata 객체를 내보내 메타데이터를 관리한다. 이번 수정은 두 가지를 했다:

  1. NEXT_PUBLIC_APP_URL 환경 변수 사용: 빌드 타임에 환경 변수를 읽어 og:url 을 동적으로 설정한다. 환경별로 .env.development, .env.staging, .env.production 파일을 나누면 각 환경이 자신의 도메인을 사용하게 된다.

  2. metadataBase 추가: Next.js 의 metadata API 는 상대 URL을 절대 URL 로 변환할 때 baseUrl 이 필요하다. og:image 가 /images/og.png 같이 상대 경로로 지정되면 metadataBase 를 통해 https://own1second.com/images/og.png 로 변환된다. metadataBase 를 빠뜨리면 절대 URL 이 필요한 og:image 같은 필드가 제대로 처리되지 않는다.

// 수정 후 예상 패턴
export const metadata = {
  metadataBase: new URL(process.env.NEXT_PUBLIC_APP_URL || 'http://localhost:3000'),
  openGraph: {
    url: process.env.NEXT_PUBLIC_APP_URL,
    title: 'Page Title',
    image: '/images/og.png', // metadataBase 덕분에 자동으로 절대 URL 로 변환됨
  },
}

팀과 코드리뷰 관점

이런 실수가 자주 나오는 이유는 개발할 때는 localhost 에서만 테스트하므로 하드코딩된 도메인이 "잘 돌아가" 보이기 때문이다. 스테이징이나 프로덕션에 올라갔을 때 문제가 드러나는데, 그땐 이미 PR 이 머지된 뒤고 누군가는 "왜 공유된 페이지가 틀린 썸네일로 나와?" 라고 물어본다.

코드리뷰할 때는 환경 변수에 의존하는 값들(도메인, API 엔드포인트, 기능 플래그 등)이 제대로 주입되는지 보는 게 중요하다. 특히 메타데이터나 SEO 관련 코드는 화면에 직접 눈에 띄는 버그가 아니라 배포 후 검색 엔진이나 SNS 파서가 읽는 데이터라서 더 체크하기 쉬우면서도 놓치기 쉽다. 팀원과 공유할 때는 "dev 환경에서 공유 버튼 테스트했을 때 OG URL 값이 뭔지 확인해 봤나?" 정도를 물어보는 게 도움이 된다.

tsconfig.tsbuildinfo 파일 변경은 TypeScript 캐시 무효화인데, 메타데이터 관련 타입이나 환경 변수 타입이 추가되면서 자동으로 갱신된 것으로 보인다. 빌드 일관성을 위해 커밋에 포함되는 게 맞다.

🛒 이 글과 어울리는 추천 상품

*위 링크는 쿠팡파트너스 활동의 일환이며, 일정액의 수수료를 제공받을 수 있습니다.

이어보기

댓글 0

첫 댓글 달아줘.