빌드 프로세스

이 문서는 앱인토스 Unity SDK의 전체 빌드 파이프라인을 상세히 설명해요.

빌드 파이프라인 개요

빌드는 3개의 주요 단계로 구성돼요:

┌─────────────────────────────────────────────────────────────────────┐
│                        Entry Points                                 │
│  Menu: Build & Package  │  Build Window  │  Server Start/Restart    │
└─────────────┬───────────────────────────────────────────────────────┘
              │
              ▼
┌─────────────────────────────────────────────────────────────────────┐
│  AITConvertCore.DoExport(buildWebGL, doPackaging, cleanBuild,      │
│                          profile, profileName)                      │
└─────────────┬───────────────────────────────────────────────────────┘
              │
     ┌────────┴────────────────────────────────┐
     ▼                                         ▼
┌──────────────────────┐          ┌────────────────────────────────┐
│  Phase 1: WebGL 빌드 │          │  Phase 2: 패키징               │
│  BuildWebGL()         │          │  GenerateMiniAppPackage()      │
│                       │          │  → AITPackageBuilder            │
│  산출물: webgl/       │          │  산출물: ait-build/dist/       │
└──────────────────────┘          └────────────────────────────────┘

호출 매트릭스

진입점	buildWebGL	doPackaging	cleanBuild
`Build & Package`	`true`	`true`	`false`
`Build & Package (clean)`	`true`	`true`	`true`
`Publish` (재빌드)	`true`	`true`	`true`
`Dev Server Start`	`true`	`true`	`false`
`Prod Server Start`	`true`	`true`	`false`
`Restart Server`	`true`	`true`	`false`
`Restart (server-only)`	—	—	—

INFO

Restart (server-only)는 DoExport를 호출하지 않고 granite 프로세스만 재시작해요.

Phase 0: 초기화

템플릿 동기화

빌드 전에 SDK의 WebGL 템플릿을 프로젝트로 복사해요.

SDK 템플릿 검색 순서:

Packages/im.toss.apps-in-toss-unity-sdk/WebGLTemplates/
Packages/com.appsintoss.miniapp/WebGLTemplates/
Assembly 경로 기반

동작:

프로젝트에 Assets/WebGLTemplates/AITTemplate/이 없으면 전체 복사해요.
있으면 마커 기반 업데이트를 수행해요 (사용자 커스텀 영역 보존).

빌드 설정

Unity PlayerSettings를 자동 구성해요:

설정	값	비고
WebGL Template	`PROJECT:AITTemplate`	하드코딩
Linker Target	`Wasm`	하드코딩
Scripting Backend	`IL2CPP`	하드코딩
Memory Size	256~1536MB	Unity 버전별 기본값 (사용자 오버라이드 가능)
Compression	`Disabled`	기본값
Threading	`false`	기본값 (모바일 브라우저 호환성)
Data Caching	`false`	기본값

버전별 기본 메모리:

Unity 2021.3: 256MB
Unity 2022.3: 512MB
Unity 6 (2023.3+): 1024MB
Unity 2024.2+: 1536MB

Config 검증

빌드 전에 설정을 검증해요:

config.appName이 비어있으면 INVALID_APP_CONFIG 에러가 발생해요.
config.iconUrl이 비어있으면 INVALID_APP_CONFIG 에러가 발생해요 (필수 필드).

Phase 1: WebGL 빌드

실행 흐름

1. AITBuildInitializer.Init(profile)
   ├── PlayerSettings 자동 구성
   ├── 환경 변수 오버라이드 적용
   └── 빌드 프로필 로그 출력

2. cleanBuild인 경우:
   └── webgl/ 디렉토리 삭제

3. BuildPipeline.BuildPlayer()

4. BuildReport 검사
   ├── 성공 → .ait-build-info.json 작성
   └── 실패 → 에러 반환

5. 빌드 마커 작성: webgl/.ait-build-info.json

빌드 마커

성공적인 WebGL 빌드 후 webgl/.ait-build-info.json에 메타데이터를 기록해요:

json

{
  "sdkVersion": "1.7.0",
  "buildTime": "2024-03-01T12:00:00.0000000Z",
  "compressionFormat": 0,
  "profileName": "Production",
  "unityVersion": "6000.2.15f1"
}

빌드 캐시 유효성 검증

WebGL 빌드 전에 기존 빌드 캐시를 검증해요:

cleanBuild=true → 무조건 clean build
webgl/ 폴더 없음 → 새 빌드 (clean 불필요)
빌드 마커 없음 → clean build (이전 SDK 버전 또는 손상)
Unity 버전 불일치 → clean build (빌드 결과물 호환 보장)
Build/*.loader.js 없음 → clean build (필수 파일 누락)
모두 통과 → 증분 빌드

Phase 2: 패키징

전체 흐름

PreparePackaging()
├── Node.js/pnpm 설치 대기
├── ait-build/ 디렉토리 생성
├── BuildConfig 복사 (SDK → ait-build/)
│   ├── package.json, tsconfig.json
│   ├── vite.config.ts (호스트/포트 치환)
│   └── granite.config.ts (앱 메타데이터 치환)
├── WebGL → public 복사
│   ├── Build, TemplateData, Runtime → public/
│   ├── index.html 플레이스홀더 치환
│   └── 로딩 화면 삽입
└── ValidateNodeModulesIntegrity()

pnpm install (3단계 재시도)
├── 1차: pnpm install --frozen-lockfile
├── 2차: pnpm install --no-frozen-lockfile
└── 3차: node_modules 삭제 + pnpm install

granite build
├── 1차: pnpm run build
└── 실패 시: CleanNodeModules → install → build 재시도

산출물: ait-build/dist/

플레이스홀더 치환

granite.config.ts 치환

플레이스홀더	치환 값
`%AIT_APP_NAME%`	앱 ID
`%AIT_DISPLAY_NAME%`	표시 이름
`%AIT_PRIMARY_COLOR%`	브랜드 색상
`%AIT_ICON_URL%`	아이콘 URL
`%AIT_VITE_HOST%`	호스트
`%AIT_VITE_PORT%`	포트
`%AIT_PERMISSIONS%`	JSON 문자열
`%AIT_OUTDIR%`	출력 디렉토리

index.html 치환

플레이스홀더	치환 값
`%UNITY_WEBGL_LOADER_URL%`	`Build/{loaderFile}`
`%UNITY_WEBGL_DATA_URL%`	`Build/{dataFile}`
`%UNITY_WEBGL_FRAMEWORK_URL%`	`Build/{frameworkFile}`
`%UNITY_WEBGL_CODE_URL%`	`Build/{wasmFile}`
`%AIT_IS_PRODUCTION%`	`"true"` / `"false"`
`%AIT_LOADING_SCREEN%`	`loading.html` 전체 내용

파일 시그니처 탐지 및 검증

WebGL 빌드 산출물의 존재 및 무결성을 검증해요.

압축 포맷별 파일 패턴

compressionFormat	의미	data 패턴	framework 패턴	wasm 패턴
`0`	Disabled	`*.data`	`*.framework.js`	`*.wasm`
`1`	Gzip	`*.data.gz`	`*.framework.js.gz`	`*.wasm.gz`
`2`	Brotli	`*.data.br`	`*.framework.js.br`	`*.wasm.br`
`-1` (기본)	폴백	`.data`	`.framework.js`	`.wasm`

INFO

loader.js는 압축 설정과 무관하게 항상 *.loader.js 패턴으로 검색돼요.

Node.js / pnpm 관리

SDK는 시스템 설치와 무관하게 자체 Node.js를 사용해요.

항목	값
Node.js	v24.13.0
pnpm	10.28.0
설치 경로	`~/.ait-unity-sdk/nodejs/v24.13.0/{platform}/`

다운로드 미러 (폴백 순서):

https://nodejs.org/dist/ (공식)
https://cdn.npmmirror.com/binaries/node/ (중국 미러)
https://repo.huaweicloud.com/nodejs/ (Huawei 미러)

에러 코드

코드	의미	조치
`NODE_NOT_FOUND`	Node.js 없음	nodejs.org에서 설치 후 에디터 재시작
`BUILD_WEBGL_FAILED`	WebGL 빌드 실패	콘솔 에러 확인, WebGL Build Support 설치 확인
`INVALID_APP_CONFIG`	앱 설정 오류	아이콘 URL(필수), 앱 ID 확인
`NETWORK_ERROR`	네트워크 오류	인터넷 연결, npm 레지스트리, 방화벽/프록시 확인
`FAIL_NPM_BUILD`	pnpm 빌드 실패	콘솔 확인, ait-build에서 pnpm install, Node.js 재설치
`BUILD_FOLDER_MISSING`	Build 폴더 없음	Build & Package 실행
`REQUIRED_FILE_MISSING`	필수 파일 누락	Clean Build 실행
`INDEX_HTML_MISSING`	index.html 없음	WebGL Templates 재생성
`PLACEHOLDER_SUBSTITUTION_FAILED`	플레이스홀더 미치환	Clean Build 실행

빌드 프로세스 ​

빌드 파이프라인 개요 ​

호출 매트릭스 ​

Phase 0: 초기화 ​

템플릿 동기화 ​

빌드 설정 ​

Config 검증 ​

Phase 1: WebGL 빌드 ​

실행 흐름 ​

빌드 마커 ​

빌드 캐시 유효성 검증 ​

Phase 2: 패키징 ​

전체 흐름 ​

플레이스홀더 치환 ​

granite.config.ts 치환 ​

index.html 치환 ​

파일 시그니처 탐지 및 검증 ​

압축 포맷별 파일 패턴 ​

Node.js / pnpm 관리 ​

에러 코드 ​