آموزش جامع رفع ارور Gradle Build Failed در یونیتی ۲۰۲۰ (پاسخ به سوالات شما)

مقدمه:

سلام به همراهان همیشگی تیم UnityFarsi. ما همیشه نظرات و پیام‌های شما را می‌خوانیم و سعی می‌کنیم در سریع‌ترین زمان ممکن راهگشای مشکلات شما باشیم. اخیراً یکی از کاربران عزیز سایت پیام زیر را برای ما ارسال کرده‌اند:

“سلام و درود… من از سایت شما unity 2020 رو دانلود کردم… android support نداشت بنابراین از soft98 بصورت جداگانه دانلود و نصب کردم… ndk sdk و jdk رو هم فعال کردم با این حال هنگام خروجی گرفتن ارور gradle built failed میگیرم… لطف بزرگی می‌کردید که پاسخ بدید ممنون”

دوست عزیز، ممنون که مشکلت را با ما در میان گذاشتی. ارور Gradle Build Failed یکی از شایع‌ترین و در عین حال روی اعصاب‌ترین ارورهایی است که توسعه‌دهندگان اندروید در یونیتی با آن مواجه می‌شوند. در این مقاله می‌خواهیم قدم به قدم بررسی کنیم که چرا این اتفاق می‌افتد و چگونه باید آن را برای همیشه حل کرد.

چرا ارور Gradle Build Failed رخ می‌دهد؟

این خطا معمولاً به سه دلیل اصلی رخ می‌دهد:

۱. ناهماهنگی نسخه‌های SDK، NDK و JDK با نسخه یونیتی.

۲. مشکلات تحریم و عدم دسترسی Gradle به سرورها برای دانلود پیش‌نیازها.

۳. نصب دستی ماژول‌ها (به جای استفاده از Unity Hub).

با توجه به توضیحات شما، بیایید قدم به قدم مشکل را حل کنیم:

قدم اول: اشتباه رایج در نصب دستی ماژول‌ها (نکته طلایی)

شما اشاره کردید که ماژول Android Support را به صورت جداگانه از سایت‌های دیگر دانلود و نصب کرده‌اید. در نسخه‌های قدیمی یونیتی (مثل ۲۰۱۸ و قبل‌تر) این کار منطقی بود، اما در یونیتی ۲۰۱۹ به بعد (به خصوص ۲۰۲۰)، نصب دستی ماژول‌ها خارج از Unity Hub به شدت باعث ایجاد تداخل می‌شود.

یونیتی ۲۰۲۰ نسخه‌های بسیار خاصی از NDK و SDK را نیاز دارد و اگر شما پکیج‌های متفرقه‌ای را به آن بشناسانید، Gradle نمی‌تواند بیلد را تکمیل کند.

راه‌حل استاندارد:

بهترین کار این است که اجازه دهید خود Unity Hub ماژول اندروید را به همراه SDK، NDK و JDK مخصوص همان نسخه دانلود کند.

اگر امکان این کار را ندارید، حتماً به مسیر Edit > Preferences > External Tools در یونیتی بروید. در آنجا تیک گزینه‌های SDK، JDK، NDK و Gradle را بردارید و مسیر فایل‌هایی که خودتان دانلود کرده‌اید را به آن بدهید. (دقت کنید هیچ فاصله یا حرف فارسی در مسیر پوشه‌های شما وجود نداشته باشد).

قدم دوم: مشکل تحریم‌ها و اینترنت (مهم‌ترین دلیل در ایران)

شما به «قطعی‌ها» اشاره کردید. نکته بسیار مهم این است که Gradle برای اولین بیلد، نیاز به دانلود یک سری فایل‌ها (Dependencies) از اینترنت دارد. از آنجا که سرورهای گوگل و گریدل برای آی‌پی‌های ایران تحریم هستند، اگر اینترنت شما متصل نباشد یا ابزار گذر از تحریم نداشته باشید، فرآیند Build قطعا با خطای Gradle متوقف می‌شود.

راه‌حل:

قبل از زدن دکمه Build، حتماً از یک DNS رفع تحریم قدرتمند استفاده کنید. پیشنهاد ما استفاده از شکن (Shecan.ir)، بگذر (Begozar.ir) یا الکترو (Electro) است. برنامه‌های تغییر آی‌پی (VPN) هم اگر سرعت خوبی داشته باشند کارساز هستند. اجازه دهید اینترنت متصل بماند تا یونیتی فایل‌های گریدل را دانلود کند.

قدم سوم: رفع مشکل کش (Cache) گریدل

گاهی اوقات به دلیل تلاش‌های ناموفق قبلی، فایل‌های مخرب در کش سیستم شما ذخیره شده‌اند و حتی با درست شدن شرایط، باز هم ارور می‌دهند.

راه‌حل:

1. یونیتی را ببندید.
2. به پوشه پروژه خود بروید و پوشه Library را به طور کامل پاک کنید. (نگران نباشید، با باز کردن مجدد پروژه، یونیتی این پوشه را دوباره می‌سازد، فقط کمی زمان می‌برد).
3. به مسیر C:\Users\YourUserName\.gradle در ویندوز خود بروید و پوشه caches را پاک کنید.
4. پروژه را باز کنید و مجدداً با اینترنت آزاد (DNS) خروجی بگیرید.

قدم چهارم: استفاده از Custom Gradle Template

شما گفتید که نسخه ۶.۳ گریدل را هم تست کردید اما جواب نداد. برای استفاده از یک گریدل خاص، باید به یونیتی بگویید که از فایل پیش‌فرض خودش استفاده نکند.

1. در یونیتی به مسیر Edit > Project Settings > Player بروید.
2. در تب Android، بخش Publishing Settings را باز کنید.
3. تیک گزینه Custom Base Gradle Template و Custom Launcher Gradle Template را بزنید.
4. با این کار فایل‌های mainTemplate.gradle و launcherTemplate.gradle در پوشه Assets/Plugins/Android ساخته می‌شوند.
5. حالا مطمئن شوید پلاگین‌های اضافی یا پکیج‌هایی که با نسخه گریدل شما تداخل دارند در پروژه وجود ندارند.

جمع‌بندی و پیشنهاد نهایی به کاربر عزیزمان

دوست عزیز، در ۹۰ درصد مواقع در ایران، ارور Gradle در یونیتی ۲۰۲۰ به خاطر مشکل اینترنت و تحریم (قدم دوم) و یا ناهماهنگی نسخه‌های SDK/NDK به دلیل نصب دستی (قدم اول) است.

پیشنهاد ما این است که اگر مقدور است، یک بار ماژول اندروید را از طریق خود Unity Hub نصب کنید (تیک گزینه‌های SDK و NDK را در هاب بزنید تا خودش دانلود کند) و هنگام بیلد حتماً از یک DNS معتبر استفاده کنید.

امیدواریم این آموزش مشکل شما و سایر کاربران UnityFarsi را حل کرده باشد. اگر باز هم مشکلی بود، متن دقیق ارور (از تب Console) را برای ما در بخش نظرات کپی کنید تا دقیق‌تر بررسی کنیم. موفق باشید!