홈 SEO title 이 CMS 설정값 반영 못하던 버그 해결

홈 페이지의 <title> 태그가 DB의 CMS 설정(cms_site.meta.seo.title)에서 가져오지 못하고 있었다. Astro의 Base.astro 레이아웃을 수정해서 이 문제를 해결했다.

왜 이게 SEO 버그인가

검색 엔진은 페이지의 <title> 태그를 크롤링의 첫 번째 신호로 본다. 사용자가 검색 결과에서 보는 파란 제목도 바로 이 태그다. 만약 홈 페이지가 의도한 SEO title을 보여주지 못한다면, 검색 순위 리포팅과 실제 검색 결과가 맞지 않을 수 있고, 더 중요하게는 사용자 경험이 악화된다.

CMS에서 SEO 정책을 관리하는 이유도 여기 있다. 마케팅 팀이나 운영자가 검색 엔진 최적화를 위해 정기적으로 title 문구를 조정해야 하는데, 개발 배포 없이 DB 수정만으로 반영될 수 있어야 운영 효율성이 높아진다. 만약 title이 하드코딩되어 있거나 DB와 동기화되지 않으면, CMS 설정이 무의미해지는 것이다.

문제의 원인과 흔한 패턴

이런 버그는 보통 다음 중 하나에서 발생한다:

• 초기 개발 시 정적 title로 임시 구성 — Base 레이아웃을 먼저 만들 때 기본값을 넣어두고, 나중에 동적 배선을 깜빡한 경우
• 페이지 타입 분기 처리 누락 — 홈(/), 상품 페이지, 블로그 등 페이지별로 다른 로직이 필요한데, 특정 경로(홈)만 빠뜨린 경우
• 레이아웃 교체 시 로직 누락 — 기존 레이아웃(정상 작동)에서 새 Base.astro로 마이그레이션할 때 SEO 관련 코드를 빼먹은 경우

이번 경우도 비슷한 상황이었을 것 같다. 홈 페이지는 모든 페이지 중 가장 중요한 진입점이면서도, 다른 동적 페이지들과 달리 고정된 콘텐츠여서 "한 번 설정하면 손댈 필요 없다"는 착각이 있을 수 있다. 하지만 SEO 전략 변화나 브랜딩 리프레시가 있을 때는 홈 title도 함께 변해야 한다.

해결: Base.astro에서 DB 배선

Base.astro에서 cms_site.meta.seo.title을 읽어오도록 변경했다. 레이아웃 레벨에서 전역 CMS 설정을 참조하면, 홈뿐 아니라 다른 페이지들도 동일한 기본값 메커니즘을 활용할 수 있다.

Astro 프레임워크에서는 대부분의 SEO 관련 태그(title, meta description, og:image 등)를 동적으로 주입하는 방식을 지원한다. 레이아웃 단계에서 props나 data source로 값을 받을 수 있고, fallback 기본값도 함께 설정할 수 있다. 이번 경우는 홈 페이지라서 전역 CMS 설정의 기본값을 가져오는 것이 맞다.

회고: 작은 버그, 큰 영향

이런 SEO 버그를 해결하면서 몇 가지 배운 점들:

• 정적 콘텐츠일수록 동적 관리가 필요하다. 홈 페이지가 변하지 않는다고 생각하는 건 착각. SEO, 프로모션, 메타정보는 매번 진화한다.
• CMS 필드 추가 → 렌더링 경로까지 코드리뷰 필수. PR에서 "이 필드를 CMS에 추가했습니다"라는 설명만으로는 부족하다. "그래서 어디서 읽어서 어디에 반영되나?"를 필수로 확인해야 한다.
• SEO 관련 버그는 사소해도 우선순위가 높다. 내부 로직 조정과 다르게, 검색 노출에 직결되기 때문이다.

팀 전체가 이런 메타정보 관리에 대해 한 번쯤 헷갈려하는 경향이 있다. 다음에 비슷한 CMS 필드를 추가할 때는 "렌더링 지점까지 명시"하는 리뷰 체크리스트를 추가하면 좋을 것 같다.

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

• 기계식키보드 쿠팡에서 보기 →
• 모니터 쿠팡에서 보기 →
• 사무의자 쿠팡에서 보기 →

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