홈 화면 SEO 타이틀 DB 배선 버그 수정
목차
홈 페이지의 <title> 태그가 DB의 CMS 설정값(cms_site.meta.seo.title)이 아닌 고정된 값을 사용하고 있던 버그를 수정했다. Astro 기반 레이아웃 컴포넌트에서 메타 데이터 배선을 제대로 연결하는 작업이었다.
SEO 타이틀 관리, 왜 중요한가
사이트 타이틀은 SEO의 기본이면서도, 운영자가 서비스 이름이나 마케팅 메시지를 언제든 바꿀 수 있어야 하는 요소다. 고정 코드에 박혀 있으면 매번 배포가 필요하고, 실시간 브랜딩 변경이나 A/B 테스트도 불가능하다. 특히 멀티테넌트 구조라면 각 사이트 인스턴스마다 다른 타이틀을 가져야 한다. 우리의 경우 CMS DB에 타이틀을 저장해 두고 페이지 렌더 시 동적으로 읽어오는 구조였는데, 이번 버그는 그 배선이 제대로 안 되어 있었던 것이다.
Base.astro의 역할과 수정 내용
src/layouts/Base.astro는 모든 페이지의 HTML 헤더와 구조를 정의하는 마스터 레이아웃 파일이다. Astro 프레임워크에서 <head> 섹션 관리, 메타 태그, 스타일시트 로딩 등이 한 곳에서 처리되므로, SEO 메타 데이터의 "배선 교집합" 역할을 한다. 여기서 <title>을 결정하지 않으면 서브 페이지들도 올바른 타이틀을 가질 수 없다.
이번 수정의 핵심은 다음과 같다:
- Before: 하드코딩된 기본값(예: "Home") 또는 props 없이 고정 문자열 사용
- After: CMS DB의
cms_site.meta.seo.title값을 먼저 확인 → 없으면 폴백
코드 패턴으로는 대략 다음 방식:
// src/layouts/Base.astro
---
// props 또는 API 호출로 cms_site 데이터 수신
const { cms_site, title } = Astro.props;
// DB 값 우선, 폴백 체인 구성
const pageTitle = cms_site?.meta?.seo?.title || title || "Default Site Name";
---
<html>
<head>
<title>{pageTitle}</title>
<!-- 기타 메타 태그들 -->
</head>
<body>
<slot />
</body>
</html>
이렇게 하면 CMS에서 타이틀을 수정하면 다음 배포 없이 즉시 반영된다.
동적 메타 데이터 배선의 일반론
메타 데이터(title, description, og:image 등)는 프론트엔드 프레임워크 선택과 무관하게 항상 같은 문제가 발생한다:
| 상황 | 권장 접근 | 주의점 |
|---|---|---|
| 고정 콘텐츠 (홈, 소개) | DB/CMS에서 동적 로드 | 캐싱 레이어가 있으면 TTL 설정 필요 |
| 동적 콘텐츠 (상품, 블로그) | 페이지 생성 시점에 props로 전달 | SSR/SSG 시 템플릿 엔진이 title 삽입 |
| 다국어 지원 | locale별 메타 컬럼 또는 번역 테이블 | 폴백 언어 체인 명확히 정의 |
| OG/리치 미리보기 | Open Graph, Twitter Card 모두 포함 | CDN 캐시 무효화 자동화 |
우리가 이번에 놓친 부분은, 홈 페이지를 "고정 콘텐츠"로 취급했음에도 CMS 연동을 제대로 끝내지 않은 것이다. 운영팀이 CMS UI에서 타이틀을 수정했는데 반영이 안 되어 버그로 신고되었을 테다.
배운 점: 메타 데이터 배선은 체크리스트 사항
이런 류의 버그는 여러 이유로 발생한다:
- 첫 프로토타입: 개발 초기에 "일단 하드코딩"으로 시작 → 나중에 동적화 누락
- 프레임워크 마이그레이션: 다른 프레임워크에서 Astro로 옮길 때 메타 관리 패턴이 달라짐
- 레이아웃 리팩토링: 여러 페이지가 공유하는 마스터 레이아웃 변경 후 일부 메타 태그 갱신 누락
- 운영자 지원 누락: CMS 개발은 했는데 프론트엔드 배선까지 못 마침
앞으로 페이지 구조 정의 단계에서 "이 메타 데이터는 어디서 오는가"를 명시적으로 문서화하고, 코드 리뷰 시 메타 태그 배선을 체크하는 게 좋겠다. 특히 운영자가 관리 가능해야 하는 항목(타이틀, description, og:image)은 CMS 연동 완료까지를 하나의 태스크로 묶어야 한다. 그렇지 않으면 운영팀이 변경했는데 반영이 안 되는 상황이 계속 반복된다.
🛒 이 글과 어울리는 추천 상품
*위 링크는 쿠팡파트너스 활동의 일환이며, 일정액의 수수료를 제공받을 수 있습니다.
댓글 0
첫 댓글 달아줘.