AWS S3 + CloudFront로 배포 시 정적 파일을 불러오지 못해 흰 화면이 발생하는 문제 해결하기
(blog.lemonbase.team)배포 시 정적 파일을 불러오지 못해 흰 화면이 발생하는 문제를 AWS S3 + CloudFront로 해결한 글입니다. AWS S3 + CloudFront로 안정적인 정적 파일 배포를 고민하는 분들에게 도움이 되었으면 좋겠습니다.
[문제 발생 배경]
- React + Vite 기반 Frontend 서비스 운영
- 배포 후 간헐적 흰 화면 발생 → 정적 파일을 불러오지 못함
- 콘솔 오류: MIME 타입 불일치 (text/html 반환)
[문제 분석]
- MIME 타입 불일치: 정적 파일이 아닌 HTML 응답 반환
- Github Actions 취소 → ECS 인스턴스 제거 가설
- 배포 시점과 정적 파일 서빙 불일치
- 기존 버전의 index.html이 새로운 정적 파일을 참조하지만 파일이 제거됨
[해결 방법]
- CloudFront + S3 활용 (최종 결정)
- S3 절대 경로 사용하여 이전 버전 정적 파일 유지
- Vite 빌드 시 파일명에 commitHash, timestamp 추가 → 고유성 유지
- S3 Lifecycle 설정으로 불필요한 파일 자동 삭제
- CloudFront 연동하여 빠르고 안정적인 정적 파일 서빙
- Local, Dev, Prod 환경 별도 설정
[검증 결과]
- CloudFront + S3 방식 정상 동작 확인
- 캐싱 전략 적용: 브라우저 캐시(Cache-Control, max-age) 점검
- 파일 고유성 부여로 캐싱 무효화 필요 없음
- 이전처럼 정적 파일 누락 문제 없이 안정적인 배포 가능
[배운 점]
- 배포 환경에서 정적 파일 관리가 UX에 큰 영향을 줄 수 있다.
- 가설 검증 시 빠르고 간단한 접근 방식이 중요
- S3 + CloudFront를 활용한 배포 환경 최적화 경험
- 환경별 배포 전략(Local, Dev, Prod) 차별화 필요
- 브라우저 캐싱 동작(Cache-Control, from disk cache)에 대한 이해 필수
GeekNews Weekly에 포함된 글입니다.
에디터 코멘트 보기