CI에서 JSON-LD 데이터를 감사하며 배운 점
JSON-LD 구조화 데이터는 눈에 보이는 어떤 것도 망가뜨리지 않고 사이트에서 사라질 수 있습니다. 빌드는 성공하고, 배포도 완료됩니다. 브라우저에서 페이지를 봐도 아무런 문제가 없어 보입니다.
하지만 Googlebot은 리치 결과(rich results)를 결정하기 위해 스크립트 태그를 읽습니다. 데이터가 누락되거나 손상되어도, 몇 주 뒤 Search Console에서 경고를 보내기 전까지는 알 수 없습니다.
그래서 저는 CI 파이프라인에 배포 후 감사(post-deploy audit) 단계를 추가했습니다. 이 단계는 60초 이내에 이러한 오류를 찾아냅니다.
작동 방식:
저는 Astro로 구축하고 Cloudflare Pages를 통해 배포하는 세 개의 정적 사이트를 운영하고 있습니다. 이 사이트들은 SoftwareApplication, VideoGame, ItemList와 같은 스키마를 사용합니다. 정적 사이트이기 때문에, 템플릿 변경 한 번으로 빌드 오류 없이 수천 개의 페이지에서 스키마가 누락될 수 있습니다.
감사 스크립트는 다음과 같은 작업을 수행합니다:
• 라이브 홈페이지와 샘플 상세 페이지를 가져옵니다. • 실제 URL을 찾기 위해 라이브 사이트맵을 읽습니다. • 정규 표현식(regex)을 사용하여 모든 JSON-LD 블록을 추출합니다. • @graph 언래핑(unwrapping)을 확인하여 중첩된 항목을 찾습니다. • 찾은 @type 값을 예상 목록과 비교합니다.
저는 빌드 결과물(artifacts)이 아닌 실제 배포된 라이브 페이지를 대상으로 이 작업을 수행합니다. 이를 통해 CDN 캐싱이나 에지(edge) 전달 과정에서 발생하는 문제를 잡아낼 수 있습니다.
첫 실행에서 스크립트는 세 가지 문제를 발견했습니다:
- ossfind.com: 특정 페이지에서 ItemList 누락. 막연한 의심을 구체적인 작업으로 바꿔주었습니다.
- findindiegame.com: WebSite @id에 잘못된 http:// 프로토콜 사용. 사람이 보기에는 괜찮아 보이지만 Google에게는 일관성이 없는 복사-붙여넣기 오류였습니다.
- aiappdex.com: SoftwareApplication 스키마에서 사람이 읽을 수 있는 이름 대신 가공되지 않은 데이터베이스 ID 사용.
이것들은 실제 버그였습니다. 빌드 로그나 브라우저 검토에서는 전혀 나타나지 않았습니다.
저는 CI 단계를 non-fatal(실패로 처리하지 않음)로 설정했습니다. 감사가 문제를 발견하더라도 배포는 그대로 완료되지만, 오류는 로그에 남습니다. 이를 통해 체크 항목이 파이프라인을 차단하도록 설정하기 전에 실제 환경에서의 동작을 관찰할 수 있습니다.
이것은 완전한 검증 스위트(validation suite)가 아니라 스모크 테스트(smoke test)입니다. 사이트당 두 개의 샘플을 확인합니다. 모든 예외 케이스를 잡아낼 수는 없지만, 큰 실수가 운영 환경(production)에 한 달 동안 방치되기 전에 잡아낼 수 있습니다.