Unity WebGL 빌드 로컬 테스트와 빠른 수정 워크플로

HTTP 서버 필요

WebGL 빌드는 반드시 HTTP 서버를 통해 테스트해야 한다. file:/// 프로토콜로는 동작하지 않는다.

이유는 다음과 같다.

• CORS (Cross-Origin Resource Sharing) 정책
• WebAssembly 로딩 제한
• ServiceWorker 등록 제한

로컬 서버 실행 방법

방법 1: Python HTTP 서버

Python 3가 설치되어 있으면 다음처럼 실행한다.

# 빌드 디렉토리로 이동
cd D:\Project\Unity\GameA\Builds\webgl-build

# 서버 실행
python -m http.server 8000

브라우저 접속:

http://localhost:8000

서버 종료:

Ctrl + C

방법 2: Node.js http-server

설치 (최초 1회):

npm install -g http-server

실행:

cd D:\Project\Unity\GameA\Builds\webgl-build
http-server -p 8000

접속:

http://localhost:8000

방법 3: VS Code Live Server

1. VS Code 확장 설치
   • “Live Server” 검색 후 설치
2. 빌드 폴더 열기
   • Builds/webgl-build 폴더를 VS Code에서 연다
3. 서버 실행
   • index.html 우클릭 → “Open with Live Server”
4. 자동으로 브라우저 실행
   • 기본 포트: http://127.0.0.1:5500

방법 4: Unity Editor 빌드 후 자동 실행

Unity 에디터에서 빌드를 실행하면 자동으로 HTTP 서버가 시작된다.

1. Unity 메뉴: Build/WebGL/Build
2. 빌드가 끝나면 자동으로 브라우저가 열린다
3. Unity 내장 HTTP 서버가 실행된다

빠른 개발 워크플로

Unity 재빌드가 필요 없는 파일

다음 파일은 빌드물에서 직접 수정한 뒤 브라우저 새로고침만으로 테스트할 수 있다.

수정 가능한 파일

Builds/webgl-build/
├── index.html                    # HTML 구조, JavaScript 로직
├── TemplateData/
│   ├── style.css                 # 스타일, 레이아웃, 위치 조정
│   ├── progress-bar-*.png        # 이미지 교체
│   ├── favicon.ico               # 파비콘
│   └── ...
├── manifest.webmanifest          # PWA 설정
└── ServiceWorker.js              # 서비스 워커

Unity 재빌드가 필요한 경우

Assets/WebGLTemplates/CustomTemplate/
├── index.html                    # 템플릿 파일 수정
├── TemplateData/style.css        # 템플릿 스타일 수정
└── ...

그 밖에 다음 경우에도 재빌드가 필요하다.

• Unity C# 스크립트 수정
• 씬(Scene) 변경
• 에셋(Asset) 추가/수정
• 빌드 설정 변경

빠른 테스트 4단계

1단계: HTTP 서버 실행 (최초 1회)

cd D:\Project\Unity\GameA\Builds\webgl-build
python -m http.server 8000

서버는 계속 켜 둔다.

2단계: 파일 수정

빌드물의 파일을 직접 수정한다.

예시: 로딩바 위치 변경

Builds/webgl-build/TemplateData/style.css

/* 수정 전 */
#unity-loading-bar {
  position: absolute;
  left: 50%;
  top: 60%;
  transform: translate(-50%, -50%);
  display: none
}

/* 수정 후 */
#unity-loading-bar {
  position: absolute;
  left: 50%;
  top: 70%;  /* 변경 */
  transform: translate(-50%, -50%);
  display: none
}

3단계: 브라우저에서 강력 새로고침

주의

일반 새로고침(F5)은 캐시 때문에 변경사항이 안 보일 수 있다.

강력 새로고침 단축키:

Windows/Linux:

Ctrl + Shift + R

macOS:

Cmd + Shift + R

또는 브라우저 주소창에서:

Ctrl + F5

4단계: 변경사항 즉시 확인

브라우저에서 수정된 내용이 바로 적용된다. 만족할 때까지 2~3단계를 반복한다.

템플릿 vs 빌드물 수정 비교

구분	템플릿 수정	빌드물 수정
경로	Assets/WebGLTemplates/CustomTemplate/	Builds/webgl-build/
재빌드 필요	필요	불필요
테스트 속도	느림 (수 분)	빠름 (즉시)
용도	최종 확정된 변경사항	빠른 실험 및 테스트
다음 빌드 반영	자동 반영	사라짐

권장 개발 프로세스

1단계: 빌드물에서 빠른 테스트

# 빌드물 수정 → 빠르게 실험
Builds/webgl-build/TemplateData/style.css

장점:

• 즉시 확인 가능
• 여러 값을 빠르게 시도
• Unity 재빌드 불필요

2단계: 템플릿에 최종 반영

만족스러운 결과를 얻으면 템플릿 파일에 복사한다.

# 템플릿 파일에 복사
Assets/WebGLTemplates/CustomTemplate/TemplateData/style.css

이유:

• 다음 빌드 시 자동 적용
• 팀원과 공유 가능
• Git으로 버전 관리

3단계: Unity 재빌드로 최종 확인

Unity 메뉴: Build/WebGL/Build

확인사항:

• 템플릿 변경사항이 올바르게 적용되었는지
• Unity 변수 치환이 정상 동작하는지 ({{{ WIDTH }}}, {{{ PRODUCT_NAME }}} 등)

실전 예시: 로딩바 위치 조정

목표: 로딩바를 화면 하단 쪽에 배치한다.

1. 빌드물에서 실험

Builds/webgl-build/TemplateData/style.css

#unity-loading-bar { top: 50%; }  /* 테스트 1 */

→ Ctrl + Shift + R → 화면 중앙이라 목표(하단 쪽)보다 높다

#unity-loading-bar { top: 70%; }  /* 테스트 2 */

→ Ctrl + Shift + R → 목표 위치에 맞는다

2. 템플릿에 반영

Assets/WebGLTemplates/CustomTemplate/TemplateData/style.css

#unity-loading-bar {
  position: absolute;
  left: 50%;
  top: 70%;  /* 최종 확정 */
  transform: translate(-50%, -50%);
  display: none
}

3. Git 커밋

git add Assets/WebGLTemplates/CustomTemplate/TemplateData/style.css
git commit -m "Move loading bar to 70% vertical position"

모바일 테스트

1. 같은 네트워크에서 테스트

PC에서 서버 실행

# 모든 네트워크 인터페이스에서 접근 허용
python -m http.server 8000 --bind 0.0.0.0

PC의 로컬 IP 확인

Windows:

ipconfig

macOS/Linux:

ifconfig

모바일 브라우저에서 접속

확인한 PC의 로컬 IP로 접속한다.

http://<PC 로컬 IP>:8000

PC와 모바일이 같은 WiFi에 연결되어 있어야 한다.

2. Chrome DevTools 모바일 에뮬레이션

1. DevTools 열기
   • F12 또는 우클릭 → “검사”
2. Device Toolbar 활성화
   • Ctrl + Shift + M (Windows/Linux)
   • Cmd + Shift + M (macOS)
3. 기기 선택
   • 상단 드롭다운에서 모바일 기기 선택
   • 예: iPhone 14 Pro, Galaxy S23
4. 화면 회전 테스트
   • 회전 아이콘을 눌러 세로/가로 모드를 전환한다

개발자 도구 활용

실시간 CSS 테스트

1. DevTools 열기

   F12 또는 우클릭 → 검사

2. Elements 탭에서 CSS 직접 수정
   • 요소 선택 → Styles 패널에서 값 변경
   • 실시간으로 결과 확인
3. 마음에 드는 값 찾기
   • 여러 값을 실험한다
4. 최종값을 실제 파일에 적용
   • Builds/webgl-build/TemplateData/style.css에 복사한다

캐시 비활성화 (권장)

개발 중에는 캐시를 비활성화해 강력 새로고침 없이 최신 파일을 받는다.

1. DevTools 열기 (F12)
2. Network 탭 선택
3. “Disable cache” 체크
4. DevTools를 열어 둔 상태로 개발
   • 일반 새로고침(F5)만으로도 최신 파일을 로드한다

테스트 체크리스트

데스크톱 테스트

• 로딩 프로그레스 바 표시 (화면 60% 위치)
• Unity 로고 미표시 확인
• 게임 정상 로드
• 전체화면 버튼 동작 (SHOW_DIAGNOSTICS 활성화 시)
• 반응형 레이아웃 (브라우저 크기 조정 시)

모바일 테스트

• 세로 모드: “Please rotate your device” 메시지 표시
• 가로 모드: 정상 게임 실행
• 화면 회전 시 자동 전환
• Screen Orientation API 동작 (지원 브라우저)
• 터치 입력 정상 동작

빌드 파일 확인

• ASTC 텍스처 (모바일): webgl-buildMobile.data
• DXT 텍스처 (데스크톱): webgl-build.data
• ServiceWorker 등록 확인

문제 해결

빌드가 로드되지 않는 경우

1. 브라우저 콘솔 확인
   • F12 → Console 탭
   • 에러 메시지 확인
2. 파일 경로 확인
   • Build/ 폴더에 .data, .wasm, .framework.js 파일이 있는지 확인
3. 서버 실행 확인
   • 콘솔에 “Serving HTTP on…” 메시지가 있는지 확인

CORS 에러 발생 시

• file:/// 프로토콜로 열지 않았는지 먼저 확인한다
• HTTP 서버를 통해 접속해야 한다

ServiceWorker 에러

• HTTPS 또는 localhost에서만 동작한다
• 프로덕션 배포 시 HTTPS가 필수다

변경사항이 안 보일 때

1. 강력 새로고침

   Ctrl + Shift + R

2. 캐시 완전 삭제

   F12 → Network → "Disable cache" 체크
   또는
   브라우저 설정 → 캐시 삭제

3. 파일 저장 확인
   • 편집기에서 파일이 저장되었는지 확인
4. 파일 경로 확인
   • Builds/webgl-build/ 경로가 맞는지 확인
   • 다른 빌드 폴더(Debug, Release)를 보고 있지 않은지 확인

모바일에서 접속 안 됨

1. 방화벽 확인
   • Windows Defender 방화벽에서 Python 허용
2. 같은 네트워크 확인
   • PC와 모바일이 같은 WiFi에 연결되어 있는지 확인
3. IP 주소 확인
   • ipconfig 결과의 IPv4 주소 사용
   • VPN 사용 시 비활성화

서버 포트 충돌

OSError: [Errno 48] Address already in use

해결:

# 다른 포트 사용
python -m http.server 8001

# 또는 기존 프로세스 종료
# Windows: 작업 관리자에서 python.exe 종료
# macOS/Linux: lsof -ti:8000 | xargs kill

빌드 구조

D:\Project\Unity\GameA\Builds\webgl-build\
├── Build/
│   ├── webgl-build.data (DXT 텍스처 - 데스크톱)
│   ├── webgl-build.framework.js
│   ├── webgl-build.loader.js
│   ├── webgl-build.wasm
│   ├── webgl-buildMobile.data (ASTC 텍스처 - 모바일)
│   ├── webgl-buildMobile.framework.js
│   ├── webgl-buildMobile.loader.js
│   └── webgl-buildMobile.wasm
├── TemplateData/
│   ├── style.css
│   ├── progress-bar-*.png
│   └── ...
├── index.html
├── manifest.webmanifest
└── ServiceWorker.js

주의사항

빌드물 수정은 임시적이다

빌드를 다시 실행하면 빌드물의 수정사항은 사라진다.

올바른 흐름:

빌드물 수정 (빠른 테스트)
  → 만족스러운 결과
  → 템플릿에 반영
  → Git 커밋

Unity 변수 주의

템플릿에는 Unity 변수가 들어 있다.

<!-- 템플릿 -->
<title>{{{ PRODUCT_NAME }}}</title>

<!-- 빌드물 (변수 치환됨) -->
<title>GameA</title>

빌드물을 수정할 때는 다음을 주의한다.

• 이미 치환된 값만 보인다
• 템플릿 변수 문법이 보이지 않는다
• 템플릿에 반영할 때 치환된 값을 그대로 옮기지 않고 Unity 변수로 되돌린다

추가 팁

VS Code에서 빠른 편집

# 빌드물 폴더를 VS Code에서 열기
code D:\Project\Unity\GameA\Builds\webgl-build

장점:

• 파일 트리 확인
• 여러 파일 동시 편집
• 통합 터미널에서 서버 실행

여러 버전 동시 테스트

# 포트를 다르게 해서 여러 빌드 동시 실행
cd Builds/webgl-build
python -m http.server 8000

cd Builds/Debug
python -m http.server 8001

cd Builds/Release
python -m http.server 8002

브라우저 탭을 바꿔 가며 빌드를 비교한다.

참고 링크

• Unity WebGL 공식 문서
• WebGL 텍스처 압축
• Screen Orientation API
• Chrome DevTools 문서
• Firefox Developer Tools