유니티 안드로이드 빌드 오류 종합 해결 가이드: Gradle 충돌부터 AAB 최적화까지

유니티 안드로이드 빌드 오류 종합 해결 가이드: Gradle 충돌부터 AAB 최적화까지

서론: 개발자를 괴롭히는 빌드 오류의 모든 것

유니티 프로젝트의 안정적인 안드로이드 빌드는 앱 성공의 필수 조건입니다. 하지만 다양한 플러그인과 지속적인 정책 변경은 개발자에게 예기치 않은 문제를 안겨주곤 합니다. 이 가이드는 제가 직접 겪고 해결했던 다양한 문제들, 즉 Gradle 충돌, 용량 최적화, Minify 설정 등 유니티 개발자가 흔히 겪는 문제들을 총망라하여 정리했습니다.

---

1. 핵심 문제: Google 서비스 플러그인 충돌 해결

오류 내용: Gradle Error: Colliding Attributes라는 경고와 함께 meta-data#...OPTIMIZE_INITIALIZATION@value=true in ... collides with another value 같은 메시지가 표시됩니다. 이는 AdMob, IAP, GPGS 등 여러 Google 관련 플러그인이 AndroidManifest.xml에 같은 설정을 서로 다른 값으로 추가하려 할 때 발생합니다.

해결 방법: Custom Main Manifest를 사용한 강제 덮어쓰기

• 원인: Gradle 빌드 시스템이 여러 플러그인의 Manifest 설정을 병합하는 과정에서 동일한 속성에 대한 우선순위를 결정하지 못해 발생합니다.
• 해결책:
  1. Player Settings → Publishing Settings에서 Custom Main Manifest를 체크합니다.
  2. Assets/Plugins/Android/AndroidManifest.xml 파일을 열고, <manifest> 태그에 xmlns:tools="http://schemas.android.com/tools"를 추가합니다.
  3. <application> 태그 내에 충돌하는 메타데이터를 tools:replace="android:value"와 함께 추가하여 강제로 값을 덮어씁니다.

대안: Custom Main Manifest 사용을 피하고 싶다면, 모든 플러그인을 최신 버전으로 유지하고, Assets > External Dependency Manager > Android Resolver > Force Resolve를 주기적으로 실행하여 종속성 충돌을 자동 해결할 수 있습니다.

---

2. 필수 빌드 설정 및 용량 최적화

문제 상황: AAB(Android App Bundle) 빌드를 통해 앱 용량을 최적화하고 싶지만, 설정이 복잡합니다. 또한 Minify 기능을 켰을 때 발생하는 런타임 오류도 있습니다.

해결 방안:

• AAB와 용량 최적화:
  • AAB는 사용자 기기에 최적화된 APK를 생성하여 앱 크기를 평균 15~20% 감소시킵니다.
  • Addressables 시스템을 활용해 에셋을 Fast-follow나 On-demand 모드로 설정하여 초기 다운로드 용량을 획기적으로 줄일 수 있습니다. 이 경우 OBB 파일을 생성하는 Split Application Binary 옵션은 체크하지 않습니다.
• Minify와 Proguard:
  • Player Settings에서 Custom Proguard File을 체크하고, 플러그인에서 제공하는 규칙을 추가하여 난독화 예외를 설정합니다. Anti-Cheat Toolkit 같은 플러그인은 보통 이 규칙을 자동으로 추가합니다.

---

3. 빌드 환경 관리 및 오류 대처

문제 상황: SDK 파일에 접근할 수 없다는 오류, minSdkVersion 경고, 그리고 mainTemplate.gradle 같은 파일이 중복되는 등 빌드 환경 자체에서 발생하는 문제들이 있습니다.

해결 방안:

• API 레벨 설정: Player Settings에서 Target API Level은 34로, Minimum API Level은 24로 설정하여 Google Play의 최신 정책을 준수하세요.
• 관리자 권한으로 실행: Unity Hub와 Unity Editor를 관리자 권한으로 실행하여 SDK 파일의 읽기 전용 문제와 같은 권한 오류를 방지합니다.
• 파일 정리: Assets/Plugins/Android 폴더에 mainTemplate.gradle 파일이 여러 개 중복되어 있다면, 하나만 남기고 나머지를 모두 삭제해야 합니다.
• 플러그인 폴더 정리: Android와 iOS 폴더를 제외하고, CodeStage나 Quick처럼 사용하지 않는다고 확신하는 플러그인 폴더는 삭제하여 프로젝트를 깔끔하게 관리할 수 있습니다.

---

4. 최종 요약 및 꿀팁

• 플러그인 최신화: 모든 Google 관련 플러그인은 항상 최신 버전을 유지하는 것이 충돌 방지의 첫걸음입니다.
• EDM(External Dependency Manager): Assets > External Dependency Manager 메뉴에서 모든 Google 플러그인 종속성을 관리하고, Force Resolve를 통해 자동 해결을 시도하세요.
• 코드 수정 최소화: Custom Main Manifest를 사용하지 않고 싶다면 Force Resolve를 먼저 시도하고, 그래도 안될 경우에만 Custom Gradle Template을 사용하는 것을 고려해 보세요.

이 가이드를 통해 유니티 안드로이드 빌드 문제를 체계적으로 해결하고, 개발 효율성을 높이시길 바랍니다.