diff --git a/00_Raw/2026-04-26-Skybound_Production_Visual_Mismatch_Public_Asset_Cache_Busting.md b/00_Raw/2026-04-26-Skybound_Production_Visual_Mismatch_Public_Asset_Cache_Busting.md deleted file mode 100644 index 14890ac2..00000000 --- a/00_Raw/2026-04-26-Skybound_Production_Visual_Mismatch_Public_Asset_Cache_Busting.md +++ /dev/null @@ -1,133 +0,0 @@ -# Skybound Production Visual Mismatch Public Asset Cache Busting - -작성일: 2026-04-26 20:55 KST - -## 요청 요약 - -- 로컬에서 실행하면 비주얼이 정상인데, 도메인에 빌드 결과물을 올리면 전혀 다른 비주얼로 보인다. -- 빌드가 정상적으로 되고 있는지 확인해야 한다. - -## 확인 결과 - -빌드 산출물 자체는 정상으로 확인했다. - -확인 내용: - -- 도메인 `https://koritips.com/`의 HTML이 로컬 `dist/47/index.html`과 같은 번들 파일을 참조하고 있었다. -- 원격 JS 파일 `index-DZFNJub_.js`와 로컬 `dist/47/assets/index-DZFNJub_.js`의 파일 크기와 SHA-256 해시가 동일했다. -- 새 기체/배경 SVG도 서버에서 `200 OK`와 `image/svg+xml`로 정상 응답했다. - -따라서 문제는 “빌드가 잘못됨”보다는 `public/sprites` 정적 에셋 캐시 문제일 가능성이 높다. - -## 핵심 원인 - -Vite 번들 JS/CSS는 파일명에 해시가 붙는다. - -예: - -- `index-DZFNJub_.js` -- `index-CzXPPmjz.css` - -그래서 코드가 바뀌면 브라우저가 새 파일을 받는다. - -하지만 `public/sprites/...`에 있는 이미지 파일은 파일명이 고정이다. - -예: - -- `/sprites/player/falcon_magitech.svg` -- `/sprites/background/stylized_magitech_stage_1.svg` -- `/sprites/missiles/homing_missile.png` - -Hostinger CDN은 이 파일들에 아래처럼 긴 캐시를 적용하고 있었다. - -- `cache-control: public, max-age=604800` -- 약 7일 캐시 - -즉 코드 번들은 새로 받았지만, 이미지 파일은 브라우저/CDN이 예전 캐시를 계속 사용할 수 있다. - -이 경우 로컬과 도메인의 비주얼이 달라진다. - -## 적용한 해결 방향 - -정적 이미지 URL에 asset version query를 붙여 캐시를 강제로 갱신한다. - -예: - -- 기존: `/sprites/player/falcon_magitech.svg` -- 변경: `/sprites/player/falcon_magitech.svg?v=20260426-2048` - -URL이 달라지면 브라우저와 CDN은 새 리소스로 판단한다. - -## 적용한 변경 - -### 공통 asset version helper 추가 - -추가 파일: - -- `/Volumes/Data/project/Antigravity/Skybound/src/features/game/config/assetVersion.ts` - -추가 내용: - -- `ASSET_VERSION` -- `assetUrl(path)` - -### 런타임 스프라이트 로더 캐시 버스팅 - -수정 파일: - -- `/Volumes/Data/project/Antigravity/Skybound/src/features/game/hooks/useGameAssets.ts` - -적용 대상: - -- 플레이어 기체 -- 배경 타일 -- 적/보스/엘리트 스프라이트 -- 아이템 드랍 -- supply crate -- missile/skill sprites -- VFX sprites -- hazard sprites - -### 사용자 노출 UI 이미지 캐시 버스팅 - -수정 파일: - -- `/Volumes/Data/project/Antigravity/Skybound/src/features/game/ui/TitleScreen.tsx` -- `/Volumes/Data/project/Antigravity/Skybound/src/features/game/ui/ResultCard.tsx` -- `/Volumes/Data/project/Antigravity/Skybound/src/features/game/ui/SelectCard.tsx` -- `/Volumes/Data/project/Antigravity/Skybound/src/features/game/ui/HangarOverlay.tsx` -- `/Volumes/Data/project/Antigravity/Skybound/src/features/game/stateMachine.ts` -- `/Volumes/Data/project/Antigravity/Skybound/src/features/game/config/skills.ts` -- `/Volumes/Data/project/Antigravity/Skybound/src/App.css` - -적용 대상: - -- 타이틀 배경 -- 결과 화면 배경 -- 기체 선택 이미지 -- 모듈 캐시 이미지 -- HQ 초상화 -- 스킬 아이콘 -- ending background -- CSS 기반 player preview - -## 검증 - -- `npm run build` 성공 -- 출력 디렉터리: `dist/48` -- 새 번들 파일: - - `dist/48/assets/index-BXnzL9eU.js` - - `dist/48/assets/index-DbtoIaXm.css` -- 빌드 결과에서 `20260426-2048` asset version 포함 확인 - -## 배포 시 주의 - -도메인에는 `dist/48` 폴더 자체가 아니라 `dist/48` 안의 내용을 `public_html` 루트에 업로드해야 한다. - -업로드 후에도 Hostinger CDN이 HTML을 잠깐 잡고 있을 수 있으므로 아래를 권장한다. - -- Hostinger cache purge 실행 -- 브라우저 hard refresh -- 가능하면 시크릿 창에서 확인 - -이번 변경 이후에는 `/sprites/...` 이미지 URL도 버전이 바뀌므로 기존 이미지 캐시 때문에 로컬/운영 비주얼이 달라지는 문제를 크게 줄일 수 있다. diff --git a/10_Wiki/Topics/AI/Case-Study-Skybound-Asset-Cache-Busting.md b/10_Wiki/Topics/AI/Case-Study-Skybound-Asset-Cache-Busting.md new file mode 100644 index 00000000..b26ebd4b --- /dev/null +++ b/10_Wiki/Topics/AI/Case-Study-Skybound-Asset-Cache-Busting.md @@ -0,0 +1,28 @@ +--- +id: CS-SKYBOUND-CACHE-001 +category: "[[10_Wiki/💡 Topics/AI]]" +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)을 가진 경로 생성. +- **성과:** 배포 즉시 모든 클라이언트가 최신 시각적 자산을 로드함을 보장하며, 수동 캐시 삭제 요청 없이도 완벽한 버전 동기화 달성. + +## ⚠️ 모순 및 업데이트 (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]]