Astro와 Cloudflare Pages 간 URL 정규화 및 배포 매니페스트 충돌 해결

Astro + Cloudflare Pages: 3 Deploy Bugs You'll Probably Hit

Mike2026년 6월 6일3분intermediate

AI 요약

Context

Astro 5 기반 정적 사이트를 Cloudflare Pages에 배포하며 발생한 URL 처리 및 배포 파이프라인 상의 제약 사항 분석. 플랫폼의 자동 307 리다이렉션 동작과 Astro의 빌드 설정 간 불일치로 인한 SEO 및 경로 접근성 문제 발생.

trailingSlash: 'always' 설정을 통한 Canonical URL과 Cloudflare Pages의 기본 서빙 경로 일치화
build.format: 'file' 적용 시 발생하는 307 리다이렉션 체인 및 404 오류 방지를 위해 Directory 기반 빌드 구조 유지
플랫폼 제약으로 인한 _redirects 파일의 Absolute URL 거부 문제를 Cloudflare Dashboard의 Redirect Rule로 이관하여 해결
Astro 설정 파일과 _redirects 간의 중복 정의로 인한 배포 유효성 검사 실패를 방지하기 위해 명시적 설정 단일화
빌드 모드 변경 시 잔존하는 Stale Asset Manifest로 인한 308 리다이렉션 오류를 Full Rebuild를 통한 매니페스트 강제 갱신으로 해결

실천 포인트

1. Cloudflare Pages 배포 전 `trailingSlash` 설정과 플랫폼의 서빙 규칙 일치 여부 확인

2. Cross-host 리다이렉션 필요 시 `_redirects` 파일 대신 Dashboard Redirect Rules 우선 사용

3. 빌드 포맷 변경 후 경로 오류 발생 시 Empty Commit을 통한 전체 매니페스트 재생성 수행

4. Google Search Console의 Redirect Error를 통해 Canonical URL 불일치 여부를 상시 모니터링

태그