---
id: CS-SKYBOUND-CACHE-001
category: Unified
confidence_score: 1.0
tags: [skybound, troubleshooting, cache-busting, production-deployment, vite, asset-[[Management|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)을 가진 경로 생성.
- **성과:** 배포 즉시 모든 클라이언트가 최신 시각적 자산을 로드함을 보장하며, 수동 캐시 삭제 요청 없이도 완벽한 버전 동기화 달성.

## ⚠️ 모순 및 업데이트 (Contradictions & RL Update)
- **과거 데이터와의 충돌:** 과거에는 파일명 뒤에 쿼리 스트링(`?v=1.2`)을 붙이는 방식이 선호되었으나, 일부 프록시 서버나 CDN에서 이를 무시하는 정책이 발견됨에 따라 현대 정책은 '물리적 경로 변경 정책'을 최우선으로 함.
- **정책 변화:** Antigravity 프로젝트는 모든 웹 기반 게임 엔진 배포 시 `dist/` 폴더 하위에 빌드 번호별 격리된 자산 경로를 생성하는 것을 강제하는 배포 정책을 시행함.

## 🔗 지식 연결 (Graph)
- Modern-Frontend-Engineering-Architecture, Vite-Build-[[Optimization|Optimization]], [[Frontend-Performance-Optimization-Guide|Frontend-Performance-Optimization-Guide]]
- **Raw Source:** 00_Raw/2026-04-26-Skybound_Production_Visual_Mismatch_Public_Asset_Cache_Busting.md