Antigravity Agent
2.6 KiB
2.6 KiB
id: CS-SKYBOUND-CACHE-001 category: Dev confidence_score: 1.0 tags: [skybound, troubleshooting, cache-busting, production-deployment, vite, asset-Management] last_reinforced: 2026-04-26
Case Study: Skybound Production Visual Mismatch & Asset Cache Busting (사례 연구: Skybound 자산 캐시 버스팅)
📌 한 줄 통찰 (The Karpathy Summary)
"빌드 번호가 바뀌어도 브라우저가 옛날 자산을 고집한다면, 파일 경로에 물리적인 버전 식별자를 주입하여 캐시의 고집을 꺾고 모든 사용자에게 동일한 시각적 진실을 강제하라" — 프로덕션 환경의 자산 불일치 해결 전략.
📖 구조화된 지식 (Synthesized Content)
- 핵심 문제: Skybound 프로덕션 배포 후, 코드(JS/CSS)는 업데이트되었으나 이미지 및 스프라이트 자산이 브라우저 캐시에 의해 구버전으로 유지되어 UI가 깨지거나 잘못된 스프라이트가 렌더링되는 현상 발생.
- 해결 전략: Hierarchical Versioned Path Injection
- Physical Directory Partitioning:
dist/[BUILD_NUMBER]/assets와 같이 최상위 경로에 빌드 번호를 포함시켜 기존 캐시를 완전히 무효화. - Manifest-driven Asset Loading: 런타임에서
buildinfo.json또는 환경 변수를 참조하여 현재 활성화된 빌드 경로에서 자산을 로드하도록 엔진 수정. - Vite Configuration Update:
vite.config.ts의build.outDir을 동적으로 할당하여 빌드마다 고유한 지문(Fingerprint)을 가진 경로 생성.
- Physical Directory Partitioning:
- 성과: 배포 즉시 모든 클라이언트가 최신 시각적 자산을 로드함을 보장하며, 수동 캐시 삭제 요청 없이도 완벽한 버전 동기화 달성.
⚠️ 모순 및 업데이트 (Contradictions & RL Update)
- 과거 데이터와의 충돌: 과거에는 파일명 뒤에 쿼리 스트링(
?v=1.2)을 붙이는 방식이 선호되었으나, 일부 프록시 서버나 CDN에서 이를 무시하는 정책이 발견됨에 따라 현대 정책은 '물리적 경로 변경 정책'을 최우선으로 함. - 정책 변화: Antigravity 프로젝트는 모든 웹 기반 게임 엔진 배포 시
dist/폴더 하위에 빌드 번호별 격리된 자산 경로를 생성하는 것을 강제하는 배포 정책을 시행함.
🔗 지식 연결 (Graph)
- Modern-Frontend-Engineering-Architecture, Vite-Build-Optimization, Frontend-Performance-Optimization-Guide
- Raw Source: 00_Raw/2026-04-26-Skybound_Production_Visual_Mismatch_Public_Asset_Cache_Busting.md