يعد نشر تطبيق Vite/React على صفحات GitHub إنجازًا مثيرًا، ولكن العملية قد تأتي في بعض الأحيان مع تحديات غير متوقعة، خاصة عند التعامل مع الصور والأصول. سيرشدك منشور المدونة هذا خلال العملية بأكملها، بدءًا من النشر الأولي وحتى استكشاف المشكلات الشائعة وإصلاحها والتوصل إلى حلول فعالة.

سواء كنت مبتدئًا أو شخصًا ذو خبرة، سيساعدك هذا الدليل على تجنب الأخطاء الشائعة ونشر تطبيق Vite/React الخاص بك بنجاح مع عرض جميع الأصول بشكل صحيح.

المتطلبات الأساسية

قبل أن نتعمق، تأكد من أن لديك ما يلي:

• مشروع Vite/React: يفترض هذا الدليل أنك قمت بإعداد مشروعك باستخدام Vite كأداة بناء و React كإطار عمل.
• مستودع GitHub: يجب أن يكون لديك مستودع GitHub موجود حيث ستدفع تطبيقك للنشر.
• تمكين صفحات GitHub: تأكد من تمكين صفحات GitHub في إعدادات المستودع الخاص بك للنشر.

الخطوة 1: تهيئة نشر المشروع وصفحات GitHub

أولاً، تأكد من تهيئة تطبيق Vite/React بشكل صحيح وأنه يعمل على المضيف المحلي. يمكنك إنشاء مشروع Vite أساسي كما يلي:

npm create vite@latest

تثبيت التبعيات:

npm install

قم بتشغيل المشروع محليًا للتأكد من أن كل شيء يعمل:

npm run dev

بمجرد أن يصبح مشروعك جاهزًا، ادفعه إلى مستودع GitHub الخاص بك.

قم بإنشاء vite.config.js لصفحات GitHub

تتوقع صفحات GitHub أن يتم تقديم التطبيق من عنوان URL أساسي محدد، وهو عادةً اسم المستودع الخاص بك. قم بتحديث ملف vite.config.js ليعكس هذا:

import { defineConfig } from 'vite'
import react from '@vitejs/plugin-react'

export default defineConfig({
  base: process.env.NODE_ENV === 'production' ? '/your-repo-name/' : '/',
  plugins: [react()],
})

يضمن الخيار الأساسي أن التطبيق يستخدم المسار الأساسي الصحيح عند النشر.

الخطوة 2: بناء ونشر المشروع

ستحتاج إلى تثبيت حزمة gh-pages للتعامل مع عملية النشر.

npm install gh-pages --save-dev

في ملف package.json الخاص بك، أضف البرامج النصية التالية لأتمتة عملية النشر:

"scripts": {
  "predeploy": "npm run build",
  "deploy": "gh-pages -d dist"
}

تشغيل النشر:

npm run deploy

في هذه المرحلة، يجب أن يكون مشروعك مباشرًا على https://.github.io//، ولكن إذا كنت مثلي، فقد تواجه بعض المشكلات مع عدم عرض التطبيق بشكل صحيح، أو عدم ظهور الصور.

الخطوة 3: المشاكل والحلول الشائعة

المشكلة 1: صفحة فارغة بعد النشر

بعد النشر، قد تلاحظ أن التطبيق يقوم بتحميل صفحة فارغة. يحدث هذا غالبًا بسبب مشكلات التوجيه. افتراضيًا، يتم استخدام BrowserRouter من React-router-dom، والذي يعتمد على التوجيه من جانب الخادم، لكن GitHub Pages يخدم ملفات ثابتة ولا يتعامل مع المسارات من جانب العميل.

الحل: استخدم HashRouter

لحل هذه المشكلة، قم بالتبديل من BrowserRouter إلى HashRouter في ملف Index.js أو main.jsx.

ملحوظة: ليس من الضروري أن يكون لديك، فهي مجرد مكتبة واجهة مستخدم مريحة أستخدمها كثيرًا في مشاريعي.

import { HashRouter } from 'react-router-dom';

createRoot(document.getElementById('root')).render(
  
);

يستخدم HashRouter رمز التجزئة (#) في عنوان URL لتتبع حالة التنقل، مما يسمح لصفحات GitHub بخدمة مسارات مختلفة بشكل صحيح دون إرجاع 404.

المشكلة 2: خطأ 404 في التحديث أو المسارات الأخرى

بعد إصلاح مشكلة الصفحة الفارغة، هناك مشكلة أخرى قد تواجهها وهي أن التطبيق يعمل على الصفحة الرئيسية ولكنه يظهر خطأ 404 عند الانتقال إلى مسارات أخرى، خاصة إذا كنت تصل مباشرة إلى مسار مثل /blogs أو /projects.

يحدث هذا لأن صفحات GitHub تعرف فقط كيفية خدمة ملف Index.html ولا تتعرف على المسارات التي يديرها React Router.

الحل: التعامل مع الأخطاء 404 في إعدادات صفحات GitHub

لإصلاح ذلك، تحتاج إلى إنشاء ملف 404.html في المجلد العام/ الخاص بك. سيضمن هذا الملف أن صفحات GitHub تخدم ملف Index.html الخاص بك لأية مسارات لا يتعرف عليها، مما يسمح لـ React Router بمعالجة التوجيه:

1. انسخ ملف Index.html إلى ملف جديد اسمه 404.html.
2. ضع هذا الملف في المجلد العام/ الخاص بك.
3. إعادة بناء المشروع وإعادة نشره.

المشكلة 3: عدم تحميل الصور أثناء الإنتاج

إحدى مشكلات النشر الأكثر شيوعًا هي عدم تحميل الصور بشكل صحيح. على الرغم من أنها تعمل بشكل جيد على المضيف المحلي، فقد تلاحظ روابط صور معطلة بعد النشر على صفحات GitHub.

على سبيل المثال، يمكنك الإشارة إلى صورة كهذه في مكوناتك:

المشكلة: مسارات الصور غير صحيحة

المشكلة هنا هي أن المسارات المطلقة (التي تبدأ بـ /) لا تعمل بشكل جيد عند نشر التطبيق في دليل فرعي (على سبيل المثال، /your-repo-name/). تحاول صفحات GitHub العثور على الصورة على https://.github.io/Images/myImage.png بدلاً من https://.github.io/your-repo-name/Images/myImage.png ، مما أدى إلى خطأ 404.

الحل: استخدم BASE_URL

لإصلاح هذه المشكلة، انقل جميع صورك إلى العامة/الصور، على الرغم من أن ذلك اختياري، فإنني أوصي بشدة أن تفعل ذلك. ستقوم بإضافة BASE_URL بشكل ديناميكي إلى مسارات الصور بناءً على البيئة:

1. تحديد ثابت BASE_URL الذي يعتمد على البيئة:

   const BASE_URL = import.meta.env.BASE_URL;

1. استخدم BASE_URL هذا عند الإشارة إلى الصور:

ملاحظة: لا تنس إزالة / الموجود أمام الصور، وإلا ستتم مضاعفته، واحد من BASE_URL والآخر من / الصور التي نسيت إزالتها.

يضمن هذا استخدام المسار الصحيح في التطوير (المضيف المحلي) وفي الإنتاج (صفحات GitHub).

الخطوة 4: النشر النهائي

بعد تنفيذ الإصلاحات الخاصة بالتوجيه ومسارات الصور، قم بإعادة بناء تطبيقك وإعادة نشره:

npm run build
npm run deploy

يجب الآن نشر تطبيق Vite/React الخاص بك بشكل كامل مع عرض جميع الصور بشكل صحيح والتعامل مع جميع المسارات بشكل صحيح.

في ملخص:

1. مشكلات التوجيه: استخدم HashRouter للتوجيه المناسب في عمليات النشر الثابتة مثل صفحات GitHub.
2. أخطاء 404 على المسارات: أنشئ ملف 404.html للتأكد من أن صفحات GitHub تخدم تطبيقك بشكل صحيح.
3. لا يتم تحميل الصور: انقل جميع الصور إلى Public/Images وألحق BASE_URL ديناميكيًا بمسارات الأصول الخاصة بك للتعامل مع بيئتي التطوير والإنتاج.

من خلال هذه الخطوات، يجب أن يكون تطبيق Vite/React نشطًا ويعمل بسلاسة على صفحات GitHub. أتمنى لك البرمجة والنشر!