Files

T

koriweb 5ba5a55c78 feat: Wiki 지식 자산 업데이트 - UX Scenarios, Frontend, Game Design, Topics 추가 [2026-05-08]

2026-05-08 19:52:07 +09:00

4.1 KiB

Raw Blame History

id, title, category, status, canonical_id, aliases, duplicate_of, source_trust_level, confidence_score, tags, raw_sources, last_reinforced, github_commit, inferred_by, tech_stack

title

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 & Updates)

과거 데이터와의 충돌: 과거에는 파일명 뒤에 쿼리 스트링(?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

🤖 LLM 활용 힌트 (How to Use This Knowledge)

언제 이 지식을 쓰는가:

(TODO)

언제 쓰면 안 되는가:

(TODO)

🧪 검증 상태 (Validation)

정보 상태: needs_review
출처 신뢰도: A
검토 이유: (P-Reinforce Phase 1 자동 정규화. 본문 검증 필요.)

🧬 중복 검사 (Duplicate Check)

기존 유사 문서: (TODO: 인덱서 클러스터 리포트 참조)
처리 방식: UPDATE (자동 정규화)
처리 이유: Phase 1 정규화 — 옛 템플릿/누락 필드 보강.

🕓 변경 이력 (Changelog)

날짜	변경 내용	처리 방식	신뢰도
2026-05-08	P-Reinforce Phase 1 정규화 (frontmatter + 헤더 표준화)	UPDATE	A

💻 코드 패턴 (Code Patterns)

패턴 1: (TODO: 이 프로젝트 컨벤션 반영한 구조 스켈레톤)

# TODO

🤔 의사결정 기준 (Decision Criteria)

선택 A를 써야 할 때:

(TODO)

선택 B를 써야 할 때:

(TODO)

기본값:

(TODO)

❌ 안티패턴 (Anti-Patterns)

[안티패턴]: (TODO: 무엇을 하면 안 되는가 + 이유 + 대신 무엇을)

4.1 KiB Raw Blame History