chore: Delete processed raw file (Skybound Cache Case)
This commit is contained in:
Antigravity Agent
@@ -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도 버전이 바뀌므로 기존 이미지 캐시 때문에 로컬/운영 비주얼이 달라지는 문제를 크게 줄일 수 있다.
|
||||
@@ -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]]
|
||||
Reference in New Issue
Block a user