نشر React

انشر تطبيق
React ثابتًا

ارفع مخرجات الإنتاج من Vite أو Create React App أو أي SPA مبنية بـ React، وانشرها مع مسار احتياطي للروابط الداخلية وHTTPS ونطاق مخصص عند الحاجة.

راجع خطوات النشر
package.json
"name": "my-react-app",
"scripts": {
"build": "vite build"
},
"dependencies": {
"react": "^18.2.0"
"react-dom": "^18.2.0"
}
تم اكتشاف مشروع React

ارفع مخرجات البناء لا ملفات المصدر

ملفات React المصدرية للتطوير. DeployPages يقدم الملفات الثابتة الناتجة من بناء الإنتاج.

Vite React

npm run build
output: dist/

المخرج الافتراضي في Vite هو dist. إذا غيّر vite.config.js قيمة build.outDir أو base فارفع المجلد الناتج الحقيقي واختبر روابط الأصول بعد النشر.

Create React App

npm run build
output: build/

يكتب CRA ملفات الإنتاج في build. إذا كان التطبيق سيعمل من مسار فرعي، فقد يؤثر إعداد homepage في روابط الأصول الناتجة.

تطبيقات React الأخرى

أمر البناء الخاص بمشروعك
output: مجلد المخرجات الثابتة

أي إعداد React يصلح عندما ينتج index.html وحزم JavaScript وCSS وصورًا وخطوطًا وأصولًا يمكن تقديمها كملفات ثابتة.

لماذا يتعطل React بعد النشر أحيانًا

تطبيق React يبدأ من مستند HTML واحد

تعتمد معظم تطبيقات React أحادية الصفحة على نقطة دخول HTML واحدة، ثم يحدد الموجه في المتصفح ما سيُعرض بعد تحميل JavaScript.

ينجح ذلك محليًا لأن خادم التطوير يعرف متى يعود إلى index.html. بعض الاستضافات الثابتة لا تفعل ذلك، لذلك قد يعمل /dashboard أثناء التنقل ثم يظهر 404 بعد التحديث.

ما الذي يتعطل عند تحديث الصفحة

يستقبل خادم الملفات الثابتة طلب GET /settings ويبحث عن ملف أو مجلد فعلي باسم settings.

تحتوي مخرجات React عادةً على index.html وأصول بأسماء hash، وقد يعيد الخادم 404 قبل أن يقرأ React Router الرابط.

GET /settings 404 (Not Found)سلوك شائع في الاستضافة الثابتة

كيف يعالج DeployPages ذلك

يستخدم DeployPages مسارًا احتياطيًا لتطبيقات SPA عند غياب مسار مستند، فيقدّم index.html بدل 404 مباشر.

بعد تحميل المستند، يبدأ React العمل، ويقرأ الموجه الرابط الحالي، وتظهر الشاشة الصحيحة دون الحاجة إلى إدارة ملفات تحويل منفصلة.

لماذا يستخدمه الفريق

ارفع مجلد dist أو build كاملًا. يصبح المسار الاحتياطي للروابط الداخلية وHTTPS والضغط والتسليم جزءًا من النشر بدل قائمة إعدادات تكررها لكل تطبيق صغير.

فحوص إنتاج يستحقها React

قد ينجح البناء ثم يفشل الرابط العام. افحص هذه النقاط قبل إرسال الموقع.

مسار الأصول الأساسي

إذا حُمّل JavaScript أو CSS من رابط خاطئ فقد تظهر صفحة بيضاء. افحص Vite base أو CRA homepage أولًا.

مسارات العميل

اختبر الدخول المباشر والتحديث لمسارات مثل /login و/pricing و/dashboard وأي رابط داخلي ترسله للآخرين.

واجهات API

يمكن لتطبيق React الثابت استدعاء واجهات API خارجية من المتصفح، لكنه لا يشغل واجهة خلفية بنفسه. أبقِ الأسرار ومفاتيح API الخاصة خارج حزمة الواجهة.

متغيرات البيئة

أغلب أدوات React تدمج القيم العامة أثناء البناء. تغيير المتغير بعد الرفع يحتاج بناء جديدًا غالبًا.

مسار نشر React

1

ابنِ التطبيق

شغّل بناء الإنتاج محليًا حتى تُجمع ملفات React وCSS والأصول في مجلد ثابت قابل للنشر.

npm run build
Produces a static output folder you can deploy directly.
2

تحقق من المخرجات

تأكد أن مجلد المخرجات يحتوي index.html والأصول المولدة. في Vite يكون غالبًا dist، وفي Create React App يكون غالبًا build.

Expected output:
dist/
├── index.html
└── assets/
3

ارفع المجلد كاملًا

اسحب مجلد dist أو build كاملًا إلى DeployPages. رفع index.html وحده سيترك الأنماط والسكربتات مفقودة.

4

اختبر مسارًا داخليًا

افتح رابطًا داخليًا ثم حدّث المتصفح وتأكد أن التطبيق ما زال يعمل بدل ظهور 404 من الاستضافة.

نصيحة عملية: إذا ظل الرابط الداخلي يعمل بعد تحديث الصفحة، فهذا يعني أن المسار الاحتياطي لتطبيق SPA يعمل كما ينبغي.

مشاكل شائعة عند نشر React

Debug 01

شاشة بيضاء بعد النشر

افتح DevTools وافحص ملفات JS أو CSS المفقودة أولًا. المسار الأساسي الخاطئ أو رفع مجلد غير صحيح سبب شائع.

Debug 02

تحديث مسار داخلي يرجع 404

تحاول الاستضافة إيجاد ملف حقيقي للمسار. استخدم المسار الاحتياطي لتطبيق SPA حتى تعيد المسارات غير الموجودة index.html.

Debug 03

الأصول تعمل محليًا ولا تعمل على الإنترنت

راجع المسارات المطلقة وإعدادات public base وتأكد أن مجلد الأصول المولدة رُفع كاملًا.

Debug 04

تغييرات متغيرات البيئة لا تظهر

أعد البناء بالقيم العامة الجديدة ثم ارفع المخرجات الجديدة. الحزمة المنشورة لا تقرأ متغيرات خادم خاصة وقت التشغيل.

أسئلة عن نشر React

Q:لماذا يظهر تطبيق React كشاشة بيضاء بعد النشر؟

غالبًا بسبب مسارات أصول خاطئة أو ملفات bundle مفقودة. في Vite افحص base، وفي CRA افحص homepage وتأكد من رفع مجلد المخرجات كاملًا.

Q:هل أحتاج إعداد nginx أو redirects يدويًا؟

لا في هذا المسار. يعالج DeployPages المسار الاحتياطي لتطبيقات SPA حتى لا تحتاج الحفاظ على قواعد تحويل خادم بنفسك.

Q:هل أرفع مجلد المشروع أم dist/build؟

ارفع مجلد مخرجات الإنتاج لا ملفات المصدر. في Vite يكون عادة dist، وفي Create React App يكون عادة build.

Q:هل يمكن استخدام متغيرات البيئة؟

نعم للقيم العامة التي تُحل أثناء البناء. DeployPages يستضيف الناتج الثابت النهائي، ولا يحقن متغيرات خادم وقت التشغيل.

Q:هل يمكن لتطبيق React استدعاء API بعد النشر؟

نعم، يستطيع استدعاء واجهات API خارجية من المتصفح. تذكر أن أي شيء داخل كود الواجهة ظاهر للمستخدمين، لذلك تحتاج الأسرار إلى واجهة خلفية.

Q:هل يمكن نشر Next.js هنا أيضًا؟

نعم إذا صدرته كموقع ثابت عبر output: export ورفعت مجلد out. مسارات SSR تحتاج بيئة تشغيل خارج الاستضافة الثابتة.

Q:هل يمكن ربط نطاق مخصص لاحقًا؟

نعم. بعد النشر، أضف النطاق في لوحة التحكم واتبع تعليمات DNS. يتم تجهيز HTTPS تلقائيًا بعد تحقق السجل.