حل مشكلة عدم تحميل Unity WebGL والأخطاء الشائعة

عندما تظهر مشكلة عدم تحميل Unity WebGL على شكل شريط تحميل متجمد أو شاشة سوداء أو رسائل حمراء في وحدة تحكم المتصفح، يكون السبب غالبًا واحدًا من خمسة: مسار ملف خاطئ، أو عدم توافق في الضغط، أو سقف للذاكرة، أو حظر CORS، أو فشل في سياق الرسوميات WebGL. هذا الدليل يمرّ على كل سبب بالترتيب الذي يجب أن تفحصه به، حتى تشغّل بناء المتصفح بدل التخمين.

الخطوة 1: افتح وحدة تحكم المتصفح أولًا

قبل أن تغيّر أي إعداد، اضغط F12 واقرأ تبويبي Console و Network. كل فشل تقريبًا في WebGL يطبع سببه الحقيقي هناك، وإصلاح الشيء الخطأ يضيّع ساعات من وقتك.

• خطأ 404 في تبويب Network يعني أن ملفًا يطلبه المُحمِّل مفقود أو اسمه خاطئ — عادةً ملف .data أو .wasm أو .framework.js.
• رسالة Unable to parse Build/xxx.framework.js.gz تعني أن الخادم يرسل ملفًا مضغوطًا دون الترويسة التي تخبر المتصفح بفك ضغطه.
• رسالة Out of memory أو Maximum call stack تشير إلى سقف الذاكرة.
• رسالة Cross-Origin Request Blocked تعني مشكلة CORS المشروحة أدناه.

اقرأ النص بدقة، فهو يدلّك على القسم الذي يجب أن تقفز إليه في هذا المقال.

الخطوة 2: علاج الشاشة السوداء عند التشغيل من file://

أكثر أسباب الشاشة السوداء شيوعًا هو النقر المزدوج على index.html وفتحه كرابط file://. المتصفحات الحديثة تحظر WebAssembly وطلبات الجلب عبر file:// لأسباب أمنية، فيموت المُحمِّل بصمت.

يجب تقديم بناء WebGL عبر بروتوكول HTTP. لاختباره محليًا، شغّل خادمًا صغيرًا من مجلد البناء:

1. افتح الطرفية داخل مجلد مخرجات البناء.
2. نفّذ الأمر python -m http.server 8000 أو npx serve.
3. افتح http://localhost:8000 في المتصفح.

إذا عملت اللعبة عبر http://localhost ولم تعمل بالنقر المزدوج، فالمسار كان هو المشكلة كلها ولا شيء آخر معطوب.

الخطوة 3: حل عدم توافق الضغط (Brotli/Gzip)

يخرج Unity البناء مضغوطًا بـ Brotli أو Gzip افتراضيًا. لن يقبله المتصفح إلا إذا أعاد الخادم ترويسة Content-Encoding الصحيحة. وإلا ستظهر رسالة Unable to parse ... .br أو .gz ويتوقف الشريط.

أمامك حلّان نظيفان:

• اضبط الخادم. أضف الترويسات بحيث تُعيد ملفات .br القيمة Content-Encoding: br، وتُعيد .wasm النوع application/wasm. على Apache يكون ذلك قاعدة في .htaccess، وعلى Nginx يكون عبر brotli_static/gzip_static.
• أو فعّل بديل فك الضغط. من Player Settings ← Publishing Settings فعّل Decompression Fallback. عندها يضمّن Unity فاكّ ضغط بلغة JavaScript فيعمل البناء حتى على استضافة ساكنة لا ترسل أي ترويسات ترميز. يكلّف ذلك وقت تحميل إضافيًا بسيطًا لكنه يلغي هذا النوع من الأخطاء بالكامل.

إذا استضفت على منصة تتولى ترويسات Unity نيابةً عنك، فستتخطى هذه الخطوة تمامًا — ولهذا فإن النشر على استضافة مصممة لهذا الغرض أفضل من مساحة تخزين ساكنة عشوائية.

الخطوة 4: إصلاح أخطاء الذاكرة في WebGL

رسالة Out of memory أو انهيار في منتصف التحميل تعني أن بناءك طلب ذاكرة أكثر مما يستطيع التبويب منحه. هذا شائع على متصفحات الجوال التي تحدّ ذاكرة التبويب الواحد أقل بكثير من الحاسوب المكتبي.

• من إعدادات Player Settings راجع قيمة Memory Size وفعّل كومة قابلة للنمو بدل تخصيص ثابت ضخم.
• قلّل حجم الحمولة الفعلية. النصوص (Textures) الكبيرة والصوت غير المضغوط هما المتهمان المعتادان. دليلنا حول تقليل حجم بناء Unity WebGL يشرح ضغط النصوص وتجريد كود المحرك وإعدادات الصوت التي تخفّض بصمة الذاكرة مباشرةً.
• اختبر في نافذة تصفح خفي دون تبويبات ثقيلة أخرى، فالإضافات والتبويبات تلتهم الذاكرة نفسها.

الخطوة 5: إزالة حظر CORS و MIME

إذا أظهرت الوحدة رسالة Cross-Origin Request Blocked أو حُمّل ملف .wasm بنوع text/html، فالمتصفح يرفض ملفات وصفها الخادم بشكل خاطئ.

• تأكد أن كل ملف بناء يُقدَّم بنوع MIME الصحيح: .wasm ← application/wasm، و.js ← application/javascript، و.data ← application/octet-stream.
• إذا كان ملف HTML للعبة وملفات البناء على نطاقات مختلفة أو على CDN، أضف ترويسة Access-Control-Allow-Origin على مضيف الملفات.
• ترجمة WebAssembly التدفقية تحتاج application/wasm؛ بدونه تلجأ بعض المتصفحات لمسار أبطأ أو تفشل تمامًا.

الخطوة 6: استبعاد فشل سياق WebGL نفسه

إذا انتهى المُحمِّل وبقيت لديك لوحة سوداء، فقد يكون سياق كرت الشاشة قد فشل. افتح chrome://gpu للتأكد من تفعيل تسريع العتاد، وحدّث تعريفات كرت الشاشة، واختبر في متصفح ثانٍ. البناء الذي يعمل في Chrome ولا يعمل داخل عارض ويب قديم غالبًا يعني أن الجهاز الهدف لا يدعم WebGL 2 — فاضبط البديل إلى WebGL 1 من Player Settings ← Other Settings ← Graphics APIs إن كنت مضطرًا لدعم الأجهزة القديمة.

انشر بناءك بأسهل طريقة

معظم هذه الأخطاء تأتي من استضافة بناء WebGL على بنية لم تُهيَّأ له أصلًا. إن كنت تفضّل أن تكتب لعبتك بدل ضبط ترويسات الخوادم، فانشرها على The Gaming Nest: ارفع بناء Unity أو Godot WebGL ونحن نقدّمه بترويسات الضغط و MIME و CORS الصحيحة، فينقر اللاعبون ويلعبون فورًا في المتصفح دون أي تنزيل. جديد على التصدير؟ ابدأ بدليل تصدير بناء Unity WebGL، ثم انشر لعبتك وشارك الرابط.