رفع خطاهای گرادل (Gradle) در خروجی گرفتن از یونیتی (Unity)

رفع خطاهای گرادل (Gradle) در خروجی گرفتن از یونیتی (Unity)

یکی از رایج‌ترین مشکلات توسعه‌دهندگان بازی در یونیتی هنگام خروجی گرفتن برای اندروید، خطاهای مربوط به Gradle است. Gradle ابزاری برای مدیریت بیلد (Build System) در اندروید است که وظیفه دارد وابستگی‌ها، پکیج‌ها و فرآیند ساخت اپلیکیشن را هماهنگ کند. از آنجا که یونیتی برای ساخت خروجی اندروید به Gradle متکی است، هر ناسازگاری یا پیکربندی اشتباه می‌تواند منجر به خطا شود.

در این مقاله به طور کامل به بررسی خطاهای رایج Gradle در یونیتی و روش‌های رفع آن‌ها می‌پردازیم.

۱. خطای Gradle build failed

علت:

استفاده از نسخه‌های قدیمی یونیتی که با SDK/NDK یا JDK جدید سازگار نیستند.
مشکل در مسیر نصب Android SDK یا NDK.

راه‌حل:

در Unity Hub → Preferences → External Tools مسیر JDK, SDK, NDK را به درستی تنظیم کنید.
مطمئن شوید از نسخه‌های پیشنهادی یونیتی استفاده می‌کنید (مثلاً Unity 2021 LTS با Android NDK r21d).
اگر همچنان مشکل دارید، در Player Settings → Publishing Settings تیک Custom Gradle Template را فعال کنید و فایل mainTemplate.gradle را به‌روزرسانی کنید.

۲. خطای مربوط به نسخه Gradle

The project is using an incompatible version of the Android Gradle plugin

علت: نسخه Gradle تعریف‌شده در یونیتی با نسخه Android Gradle Plugin ناسازگار است.

راه‌حل:

به مسیر ProjectFolder/Gradle بروید و فایل gradle-wrapper.properties را باز کنید.
مقدار distributionUrl را به یک نسخه سازگار تغییر دهید. مثال:

distributionUrl=https\://services.gradle.org/distributions/gradle-6.1.1-all.zip

دقت کنید که نسخه Gradle باید با نسخه Android Gradle Plugin هماهنگ باشد (مثلاً Gradle 6.1.1 با Plugin 4.0.1 سازگار است).

۳. خطای SDK یا NDK پیدا نشد

SDK location not found

یا

NDK not configured

راه‌حل:

در Unity Hub از بخش Installs → Add Modules، ابزارهای Android Build Support (شامل SDK و NDK) را نصب کنید.
اگر به صورت دستی SDK یا NDK نصب کرده‌اید، مسیر درست آن را در Unity → Preferences → External Tools وارد کنید.
مطمئن شوید NDK نسخه‌ای باشد که یونیتی توصیه کرده (برای نسخه‌های جدید Unity معمولاً r21d یا بالاتر).

۴. خطاهای وابستگی (Dependencies)

Could not resolve all dependencies for configuration ':classpath'

علت: یونیتی یا پلاگین‌های شما به نسخه‌های قدیمی/جدید لایبرری‌های اندروید متکی هستند که با هم ناسازگارند.

راه‌حل:

فایل mainTemplate.gradle را باز کنید و نسخه لایبرری‌ها را به‌روز کنید. مثال:

classpath 'com.android.tools.build:gradle:4.0.1'

در صورت استفاده از پلاگین‌های شخص ثالث (مثل Firebase یا AdMob)، مطمئن شوید نسخه‌های جدیدتر آن‌ها را نصب کرده‌اید.
می‌توانید از ابزار Play Services Resolver (در پکیج‌های گوگل) برای رفع تعارض وابستگی‌ها استفاده کنید.

۵. خطای مربوط به 64-بیت (ARM64)

از سال ۲۰۱۹ گوگل تمام اپلیکیشن‌ها را ملزم کرده است که نسخه ۶۴بیتی (arm64-v8a) نیز داشته باشند.

خطای رایج:

Your APK is not 64-bit compliant

راه‌حل:

در Unity → Player Settings → Other Settings → Target Architectures گزینه ARM64 را فعال کنید.
مطمئن شوید Gradle Template و NDK مورد استفاده از خروجی ۶۴بیتی پشتیبانی می‌کنند.

۶. خطای keystore و امضا (Signing)

Keystore was tampered with, or password was incorrect

علت: پسورد Keystore یا Alias به درستی وارد نشده.

راه‌حل:

در Player Settings → Publishing Settings مطمئن شوید مسیر Keystore و پسورد درست وارد شده.
اگر پسورد را فراموش کرده‌اید، باید یک Keystore جدید بسازید (Keystore قابل بازیابی نیست).

۷. خطای Out of memory در Gradle

Java heap space

علت: پروژه حجم زیادی دارد یا جاوا حافظه کافی برای ساخت پروژه ندارد.

راه‌حل:

در فایل gradle.properties مقدار زیر را اضافه کنید:

dexOptions {
    javaMaxHeapSize "4g"
}

اگر حافظه RAM شما کم است، پروژه را سبک‌تر کنید یا از سیستم قوی‌تر استفاده کنید.

نکات کلی برای پیشگیری از خطاهای Gradle

همیشه از Unity LTS استفاده کنید تا کمترین ناسازگاری را تجربه کنید.
ماژول‌های Android (SDK/NDK/JDK) را از خود Unity Hub نصب کنید.
پلاگین‌های جانبی (AdMob، Firebase، Facebook و …) را همیشه به آخرین نسخه ارتقا دهید.
در صورت بروز مشکل، فایل mainTemplate.gradle و gradle.properties را بررسی و تنظیم کنید.
اگر با خطای ناشناخته مواجه شدید، با روشن کردن Custom Gradle Template و مشاهده لاگ‌ها در Android Studio می‌توانید خطا را دقیق‌تر بررسی کنید.

جمع‌بندی

خطاهای Gradle هنگام خروجی گرفتن از یونیتی برای اندروید بسیار رایج‌اند و معمولاً به دلیل ناسازگاری نسخه‌ها، مسیرهای اشتباه SDK/NDK، یا مشکلات وابستگی پلاگین‌ها رخ می‌دهند. با رعایت نکات فوق و استفاده از ابزارهای رسمی یونیتی، می‌توانید به راحتی بیشتر این مشکلات را رفع کرده و بدون دردسر خروجی اندروید بگیرید.

منبع : وب سایت دیجی‌مک