راهنمای جامع رفع مشکلات Gradle در یونیتی: چگونه حالت Offline Mode را فعال کنیم؟

اگر شما هم یک بازی‌ساز اندروید هستید که از موتور   Unity   استفاده می‌کنید، احتمالاً بارها با کابوسی به نام   Gradle Error   مواجه شده‌اید. در حالی که یونیتی یکی از قدرتمندترین ابزارها برای ساخت بازی‌های موبایلی است، اما وابستگی شدید سیستم “گردل” به اینترنت و مخازن آنلاین، باعث شده تا توسعه‌دهندگان (به‌خصوص در ایران) با چالش‌های زیادی مثل تحریم، کندی اینترنت و خطاهای Build مواجه شوند.

در این مقاله، ابتدا بررسی می‌کنیم که گردل چیست و چرا حالت آفلاین می‌تواند فرشته نجات شما باشد، و سپس ۳ روش گام‌به‌گام برای فعال‌سازی آن را آموزش می‌دهیم.

گردل (Gradle) چیست و چرا به حالت آفلاین نیاز داریم؟

گردل یک سیستم “Build Automation” است. وظیفه آن در یونیتی این است که کدهای سی‌شارپ، کتابخانه‌ها، پلاگین‌ها و منابع گرافیکی شما را جمع‌آوری کرده و آن‌ها را به یک فایل قابل نصب اندروید (APK یا AAB) تبدیل کند.

مشکل اصلی اینجاست که گردل برای هر بار بیلد گرفتن، سعی می‌کند نسخه‌های جدید کتابخانه‌های مورد نیاز را از سرورهایی مثل Google Maven یا JCenter چک و دانلود کند. در فضای اینترنت ما، این فرآیند اغلب با خطا مواجه می‌شود.   حالت آفلاین (Offline Mode)   به گردل دستور می‌دهد که: «دور اینترنت را خط بکش و فقط از فایل‌هایی که قبلاً روی سیستم دانلود شده است استفاده کن.»

   آموزش گام‌به‌گام فعال کردن Offline Mode در گردل

نکته بسیار مهم:   قبل از انجام این مراحل، باید حداقل یک‌بار در حالی که به یک اینترنت بدون محدودیت (با استفاده از سرویس‌های عبور از تحریم) متصل هستید، از پروژه خود خروجی بگیرید تا فایل‌های اولیه دانلود و در “کش” سیستم ذخیره شوند.

روش اول: تنظیمات سراسری (Global) برای تمام پروژه‌ها

این روش مطمئن‌ترین راه است و باعث می‌شود تمام پروژه‌های یونیتی شما در این سیستم، از حالت آفلاین استفاده کنند.

  1. به پوشه کاربری خود در ویندوز بروید (معمولاً در مسیر `C:\Users\YourUserName`).
  2. وارد پوشه‌ای به نام `.gradle` شوید (اگر وجود ندارد، یک پوشه با همین نام بسازید).
  3. در این پوشه، فایلی به نام `gradle.properties` ایجاد کنید (اگر هست، آن را باز کنید).
  4. کد زیر را درون آن بنویسید و فایل را ذخیره کنید:

    org.gradle.offline=true

 هر زمان که نیاز داشتید کتابخانه جدیدی دانلود کنید، کافی است مقدار `true` را به `false` تغییر دهید.

 

روش دوم: فعال‌سازی مخصوص یک پروژه خاص در یونیتی

اگر نمی‌خواهید کل سیستم را در حالت آفلاین بگذارید و فقط برای یک پروژه خاص به این قابلیت نیاز دارید:

  1. در ادیتور یونیتی به مسیر `Edit > Project Settings` بروید.
  2. بخش `Player` را انتخاب کرده و روی تب Android   کلیک کنید.
  3. در قسمت `Publishing Settings` پایین صفحه، تیک گزینه Custom Gradle Properties Template   را بزنید.
  4. حالا به پنجره Project بروید و در مسیر `Assets/Plugins/Android` فایلی که یونیتی به تازگی ساخته (با نام `gradleTemplate.properties`) را پیدا کنید.
  5. آن را با یک ویرایشگر متن (مثل Notepad) باز کرده و خط زیر را به انتهای آن اضافه کنید:

    org.gradle.offline=true

روش سوم: استفاده از محیط Android Studio

اگر خطاهای یونیتی بسیار پیچیده شده، بهترین راه Export گرفتن است.

  1. در تنظیمات Build یونیتی، تیک Export Project   را بزنید و دکمه Export را کلیک کنید.
  2. پوشه ساخته شده را در نرم‌افزار Android Studio   باز کنید.
  3. از سمت راست صفحه، پنل Gradle   را باز کنید.
  4. روی آیکون Toggle Offline Mode   (آیکون کره زمین با خط مورب یا علامت وای‌فای قطع شده) کلیک کنید.
  5. حالا از منوی Build، گزینه Make Project را بزنید.

 

نکات طلایی برای مدیریت بهتر گردل در یونیتی

برای اینکه برای همیشه از شر خطاهای خسته‌کننده گردل خلاص شوید، این استراتژی‌ها را به کار بگیرید:

  1.       استفاده از سرویس‌های DNS مخصوص:   به جای درگیر شدن با وی‌پی‌ان‌های مختلف، تنظیمات DNS سیستم خود را روی سرویس‌هایی مثل   Shecan.ir   قرار دهید(که البته در زمان اینترنت ملی متاسفانه ممکن است بخوبی عمل نکند). این سرویس‌ها باعث می‌شوند گردل تصور کند شما خارج از ایران هستید و دانلودها بدون خطا انجام شود.
  2.       مشخص کردن مسیر دستی برای Gradle:   در تنظیمات یونیتی (`Edit > Preferences > External Tools`)، می‌توانید تیک مربوط به نسخه‌ی پیش‌فرض گردل را برداشته و آدرس یک نسخه از گردل که قبلاً دانلود کرده‌اید را به آن بدهید. این کار از دانلود مجدد موتور گردل توسط یونیتی جلوگیری می‌کند.
  3.       بک‌آپ گرفتن از پوشه Cache:   همیشه از پوشه `C:\Users\YourUserName\.gradle\caches` یک نسخه پشتیبان داشته باشید. اگر ویندوز خود را عوض کنید، با بازگرداندن این پوشه، دیگر نیازی به دانلود حتی یک مگابایت دیتا برای گردل نخواهید داشت.
  4.       حذف پوشه Library در صورت خطای مداوم:   گاهی اوقات فایل‌های کش شده خراب می‌شوند. در این مواقع، بستن یونیتی، حذف پوشه `Library` در فولدر پروژه و باز کردن مجدد آن می‌تواند بسیاری از تداخل‌های گردل را حل کند.

 

و در نهایت

سیستم Gradle علی‌رغم تمام پیچیدگی‌ها، ابزاری بسیار قدرتمند است. با استفاده از   حالت آفلاین  ، شما نه تنها سرعت بیلد گرفتن خود را چندین برابر می‌کنید، بلکه وابستگی پروژه را به پایداری اینترنت از بین می‌برید. به یاد داشته باشید که کلید موفقیت در استفاده از این حالت، داشتن یک “کش” کامل و سالم از اولین بیلد موفق است.

امیدواریم این راهنما به شما کمک کند تا با تمرکز بیشتر روی طراحی بازی و دغدغه کمتر برای مسائل فنی خروجی گرفتن، پروژه‌های خود را به اتمام برسانید. اگر سوالی در این زمینه دارید، در بخش نظرات با ما در میان بگذارید!