C YC

IT Dev who working in Republic Of Korea

1 minute read

유니티 빌드시 Gradle Error가 발생하는 원인과 해결 방법

  • Gradle 버전 불일치
    • 원인 : 프로젝트에서 사용하는 Gradle 버전과 유니티에서 사용하는 버전이 달라서 발생합니다.
    • 해결 방법
      • Edit > Preferences > External Tools > Gradle Installed with Unity체크 해제 후 수동으로 Gradle 버전 설정
      • gradle-wrapper.properties에서 Gradle버전 확인 후 맞춰줌
      • Unity가 요구하는 Gradle 버전을 공식 문서에서 확인하고 다운로드

  • Gradle 캐시 문제
    • 원인 : Gradle 빌드 캐시가 손상되거나 오래된 파일이 남아 충돌하는것이 원인인 경우 입니다.
    • 해결 방법
      • C:\Users\사용자명\.gradle폴더 삭제
      • android\build폴더 삭제 후 다시 빌드
      • Preferences > External Tools > Reset Packages to Defaults실행

  • Android SDK / NDK / JDK 버전 문제
    • 원인 : 유니티 프로젝트에서 사용하는 Android SDK, NDK, JDK 버전이 일치하지 않아 발생하는 경우 입니다.
    • 해결 방법
      • Edit > Preferences > External Tools에서 Unity가 제공하는 SDK, NDK, JDK를 사용
      • Project Settings > Player > Android에서 정확한 버전 확인
      • gradle.properties에서 org.gradle.java.home경로 수정

  • Proguard / R8 관련 오류
    • 원인 : Proguard 또는 R8이 잘못된 설정으로 인해 빌드 실패할 수도 있습니다.
    • 해결 방법
      • Assets/Plugins/Android/proguard-user.txt에서 잘못된 규칙 수정
      • radle.properties에서 android.enableR8=false설정
      • Player Settings > Publishing Settings에서 Minify옵션 비활성화

  • Internet / Network 문제
    • 원인 : 흔하지는 않지만 Gradle이 의존성을 다운로드할 때 네트워크 문제 발생하는 경우 입니다.
    • 해결 방법
      • gradle.properties에 org.gradle.daemon=false추가
      • VPN을 사용하여 Gradle 리포지토리에 접근 가능하게 설정
      • android\gradle\wrapper\gradle-wrapper.properties의 distributionUrl을 최신 버전으로 변경

  • Java Heap Space 오류
    • 원인 : Gradle 빌드 시 할당된 메모리 부족해서 발생하는 경우 입니다.
    • 해결 방법
      • gradle.properties에 아래 추가 
          org.gradle.jvmargs=-Xmx4096M
      • Unity Editor의 메모리 사용을 줄이거나 다른 프로그램 종료 후 빌드

  • Unity Gradle Template 오류
    • 원인 : mainTemplate.gradle이 손상되거나 누락되어 발생하는 경우입니다. 의외로 많이 발생합니다.
    • 해결 방법
      • Assets/Plugins/Android/mainTemplate.gradle삭제 후 재생성
      • Edit > Preferences > External Tools에서 Gradle Installed with Unity체크 후 다시 빌드

  • Keystore 관련 오류
    • 원인 : Keystore파일이 누락되거나 암호가 달라서 발생하는 경우
    • 해결 방법
      • Player Settings > Publishing Settings에서 Keystore경로 확인
      • 새 Keystore 생성 후 적용

  • Firebase / Admob 플러그인 충돌
    • 원인 : Firebase나 Admob 같은 플러그인이 잘못 설정된 경우
    • 해결 방법
      • Assets/ExternalDependencyManager/Editor/Resolver실행 후 Force Resolve
      • Plugins/Android폴더에서 중복된 .aar파일 삭제

  • Unsupported class file major version 오류
    • 원인 : JDK 버전이 낮아서 최신 Java 코드 실행 불가
    • 해결 방법
      • JDK 11 이상 설치 후 Preferences > External Tools에서 JDK 경로 변경
      • gradle.properties에서 org.gradle.java.home 수정

해결 방법에 대하여 개인적인 팁

  1. 유니티 콘솔에서 전체 에러 메시지 확인
    • Preferences > Console에서 Full Stack Trace 옵션 활성화를 해줍니다.
    • 오류 메시지를 기반으로 필요한 수정 진행합니다.

  2. Gradle 빌드 수동 실행 테스트 
     cd 프로젝트경로/Android
 ./gradlew build --stacktrace


  3. Gradle 리포지토리 수동 업데이트 
     gradle --refresh-dependencies


Top

You May Also Enjoy