Article

Astro Content Collections로 프론트매터 오류를 배포 전에 막는 방법

2026. 5. 8.

Astro 블로그를 운영하다 보면 글 내용보다 frontmatter 누락 때문에 빌드가 깨지는 일이 더 자주 생깁니다. 이 글은 title, slug, date, summary, tags, status 같은 필드를 어떻게 통제하면 좋은지, 그리고 왜 Content Collections가 초반부터 필요한지를 실제 운영 기준으로 정리한 문서입니다. Astro는 콘텐츠 컬렉션 스키마가 frontmatter를 일관되게 검증하고, 스키마를 어긴 파일이 있으면 오류를 보여준다고 설명합니다. (출처: Astro Docs - Content collections, Astro Docs - Content entry data does not match schema)

요약 박스

• frontmatter 검증은 글쓰기 편의 기능이 아니라 배포 안정성 장치입니다.
• Astro는 컬렉션 스키마를 정의하면 Zod 기반 검증과 자동 TypeScript 타이핑을 제공합니다. (출처: Astro Docs - Content collections)
• 실무에서는 “필수 필드 정의 -> slug 규칙 -> 상태 필드 분리 -> 빌드 전 검사” 순으로 굳히는 편이 빠릅니다.

최종 업데이트: 2026-05-28

작성 관점

저는 블로그 운영에서 가장 아까운 실패가 “좋은 글을 다 써놓고 metadata 실수로 배포가 막히는 경우”라고 봅니다. 그래서 작성자 자유도보다 발행 안정성을 우선하는 스키마를 선호합니다.

1. Content Collections를 먼저 붙여야 하는 이유

Astro 문서에 따르면, 스키마는 컬렉션 안의 frontmatter 또는 데이터가 일관된 형태를 가지도록 보장하며, 스키마를 정의하면 TypeScript 인터페이스도 자동 생성됩니다. 즉, 작성 시점과 렌더링 시점 모두에서 오류를 줄일 수 있습니다. (출처: Astro Docs - Content collections)

운영 관점에서는 장점이 더 단순합니다.

1. 필수값 누락을 초기에 막을 수 있습니다.
2. slug 형식을 강제해 URL 품질을 통일할 수 있습니다.
3. draft와 published를 구분해 홈, 피드, sitemap 노출을 제어하기 쉬워집니다.

2. 블로그에서 최소로 강제할 필드

제가 초반부터 고정하는 항목은 아래 정도입니다.

Astro는 Zod로 이러한 스키마를 정의할 수 있고, 컬렉션 항목이 이를 어기면 오류를 알려줍니다. 공식 오류 문서도 컬렉션 스키마와 비교해 문제를 점검하라고 안내합니다. (출처: Astro Docs - Content collections, Astro Docs - Content entry data does not match schema)

3. 실무 체크리스트: 빌드 전에 무엇을 보나

3-1. slug는 사람이 아니라 규칙이 결정하게 합니다

사람이 직접 slug를 정하면 대문자, 공백, 날짜 중복 같은 실수가 반복됩니다. 그래서 정규식으로 허용 범위를 좁혀두는 편이 낫습니다. Astro가 스키마 기반 검증을 지원하므로, 이 단계는 문서화보다 자동화가 유리합니다. (출처: Astro Docs - Content collections)

3-2. status가 없으면 초안 관리가 무너집니다

초기 블로그일수록 초안과 공개 글이 섞이기 쉽습니다. status 필드를 별도로 두면 홈과 피드에서 published만 필터링하기 쉬워집니다. 이 구분은 발행 과정의 실수를 줄이는 데 효과적입니다.

3-3. 오류는 빌드 전에 보이게 해야 합니다

Astro는 스키마 위반 시 빌드 또는 검증 흐름에서 오류를 보여줍니다. 따라서 로컬 또는 CI에서 frontmatter 검사를 먼저 돌리면, 게시 후 수정하는 비용보다 훨씬 적은 비용으로 문제를 막을 수 있습니다. (출처: Astro Docs - Content entry data does not match schema)

4. 추천 운영 순서

1. src/content.config.ts에 최소 필드를 먼저 고정합니다.
2. 새 글을 만들 때는 템플릿 frontmatter를 복사해 시작합니다.
3. 빌드 전에 frontmatter 검사를 먼저 돌립니다.
4. 공개 전에는 published 상태, 날짜, slug 중복 여부를 마지막으로 확인합니다.

FAQ

필드가 적을수록 좋은가요?

초기에는 그렇습니다. 하지만 너무 적으면 요약, 상태, 태그 같은 운영 정보가 빠져 글이 쌓일수록 관리가 어려워집니다. 최소 운영 단위를 커버하는 정도까지는 고정하는 편이 좋습니다.

MDX나 CMS를 써도 같은 원칙이 필요한가요?

필요합니다. 저장 형식이 바뀌어도 “필수 메타데이터를 강제하고, 위반 시 조기에 실패하게 한다”는 원칙은 그대로 유효합니다. Astro 공식 문서도 컬렉션 데이터의 예측 가능성을 스키마의 핵심 가치로 설명합니다. (출처: Astro Docs - Content collections)

출처

• Astro Docs - Content collections
• Astro Docs - Content entry data does not match schema