개발 slecs

Astro 메타 설명 따옴표 버그가 SEO 전반에 미친 영향

목차

메인 페이지 메타 설명을 다시 손봤다. 내용은 부실했고, Astro 컴포넌트 내 따옴표 처리도 빠졌다. 작은 수정처럼 보이지만, 이 종류 버그가 사실 얼마나 광범위한 영향을 주는지 회고해본다.

메타 설명은 더 많은 역할을 한다

처음에는 "아, description 한 줄 텍스트 수정이네" 정도로 봤다. 하지만 페이지 메타 설명이라는 건 사실 여러 채널을 통해 노출된다.

  • 검색 엔진: Google 검색 결과에 제목 아래 두세 줄로 표시되는 그 스니펫
  • Open Graph (og:description): 페이스북, 카카오톡, 슬랙 등에서 링크 공유할 때 보이는 설명
  • Twitter Card: 트위터/X에서 공유할 때의 설명
  • 브라우저 탭/히스토리: 사용자의 북마크나 방문 기록에 저장되는 정보

"부실했다"는 건, 이 모든 채널에서 사용자가 받는 첫 인상이 약했다는 뜻이다. 검색 결과에서 클릭을 유도하지 못하고, SNS 공유했을 때도 뭘 하는 서비스인지 명확하지 않으면 클릭률이 뚝 떨어진다. 팀의 관점에서 보면 마케팅과 SEO 전략이 제 역할을 못 하는 셈이다.

Astro의 따옴표 처리, 작은 함정

이번 수정에서 "Astro 따옴표 누락"이라는 게 키 포인트였다. Astro는 .astro 파일에서 JSX 같은 문법으로 컴포넌트를 쓰는데, 메타 태그를 처리할 때 문자열 인터폴레이션과 HTML 속성 처리가 함께 일어난다.

예를 들어:

<meta name="description" content={description} />

여기서 description 변수 값이 따옴표를 포함하면 어떻게 될까? 

<!-- description = "내 서비스는 '최고'입니다" -->
<meta name="description" content={description} />
<!-- 결과: content="내 서비스는 '최고'입니다" → 문제없음 -->

<!-- 하지만 description에 큰따옴표가 있으면? -->
<!-- description = 'he said "hello"' -->
<!-- 결과: content=he said "hello" → 속성값이 깨짐! -->

또는 더 심한 경우, 템플릿 리터럴이나 동적 description을 쓸 때 백틱이나 이스케이프 처리를 놓치면 HTML 파싱이 깨진다. Astro의 하이드레이션과 SSR 프로세스에서 이런 이스케이핑이 자동으로 처리되지 않는 경우가 있고, 특히 수동으로 문자열을 조합할 때 실수하기 쉽다.

이런 버그가 왜 자주 발생하는가

내가 봐온 패턴이 있다:

  1. 메타 태그는 "한 번 쓰고 잊는" 대상이다. HTML 구조나 비즈니스 로직처럼 자주 수정하지 않으니, 초기 작성이 나쁘면 오래 방치된다.

  2. 메타 태그는 테스트하기 어렵다. 렌더링된 HTML을 까서 직접 보거나, Open Graph 디버거로 확인해야 한다. 자동화된 테스트를 만들기는 번거롭다.

  3. 프레임워크마다 다루는 방식이 다르다. React Helmet, Vue의 vue-meta, Nuxt의 useHead, Astro의 SEO 컴포넌트… 각각의 이스케이핑과 타입 처리가 약간씩 다르다. 한 기술에서 다른 기술로 옮기면서 실수하기 쉽다.

우리 팀은 어떻게 다시 막을까

이 수정 후에 생각해본 개선 사항:

  • 메타 설명 길이 제약: 보통 120-160자가 검색 결과에 온전히 표시된다. 팀 가이드라인으로 명시.
  • 메타 태그 검증: 빌드 단계에서 description 콘텐츠를 파싱해서 따옴표, 앰퍼샌드(&), 부등호(<, >) 같은 특수문자가 이스케이프되어 있는지 확인하는 린터 규칙 추가.
  • 코드 리뷰 체크리스트: 메타 태그 수정하는 PR이 들어오면, "og:description과 일치하는가?", "특수문자 이스케이프?", "길이는 합리적인가?" 다시 한 번 묻기.

작은 버그지만, 이렇게 쌓이는 게 기술 부채가 된다. 다음부터는 초기 구현 단계에서 좀 더 신경 써야겠다.

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

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

이어보기

댓글 0

첫 댓글 달아줘.