تتيح استضافة Cloudflare Pages لفرق تطوير الواجهة الأمامية شحن أكواد برمجية سريعة وآمنة وخالية من تعقيدات إدارة السيرفرات. ومن خلال استخدام Cloudflare Pages ، يحصل المطورون على منصة عالية الأداء تعتمد على الحافة ونشر تطبيقات الويب الثابتة، والتطبيقات ذات الصفحة الواحدة (SPAs)، وأطر العمل المعتمدة على التصيير من جانب الخادم (SSR). ومن خلال الاتصال المباشر بمستودع Git الخاص بك، تقوم Cloudflare بأتمتة مسارات البناء، وتوليد عمليات نشر معاينة مؤقتة، واستضافة أصول وملفات موقعك عالميًا. يوضح هذا الدليل كيفية ربط مستودع Git، وتكوين إعدادات البناء، وإعداد النطاقات المخصصة، وتكوين قواعد التحويل.

أهم النقاط المستفادة:

  • نشر تطبيقات واجهة أمامية تعتمد على الحافة؛ تخدم Cloudflare Pages الأصول والملفات عالميًا من شبكة Cloudflare، مما يضمن أوقات تحميل فائقة السرعة وأقل من ثانية.
  • أتمتة تكامل مستودع Git؛ اربط مستودعك لتشغيل عمليات بناء تلقائية وتوليد روابط معاينة مميزة لكل عملية دفع كود.
  • تكوين إعدادات بناء أطر العمل المختلفة؛ حدد مجلد المخرجات النهائي وأوامر البناء لـ React أو Vue أو Next.js أو Hugo أو Astro.
  • تطبيق قواعد التحويل وتخصيص الرؤوس (Headers) باستخدام ملفات نصية بسيطة _redirects و _headers في مجلدك العام (public).
  • ربط النطاقات المخصصة مع شهادات SSL مجانية ومحدثة تلقائيًا تدار بالكامل بواسطة Cloudflare.

ما هي منصة Cloudflare Pages؟

إن منصة Cloudflare Pages هي منصة استضافة خالية من السيرفرات (serverless) لمطوري الواجهة الأمامية، تشبه منصات Vercel أو Netlify، مبنية مباشرة على البنية التحتية العالمية لشركة Cloudflare.

وبدلاً من استضافة الملفات على خادم سحابي واحد، تقوم Cloudflare Pages بتوزيع ملفات HTML و CSS و JavaScript والصور الخاصة بك عبر مواقع الحافة (edge locations) حول العالم. وعندما يطلب المستخدم موقعك، يتم تقديم هذه الأصول والملفات من أقرب موقع جغرافي له، مما يقلل من زمن انتقال الشبكة. وبالنسبة للمشاريع التي تتطلب منطقًا برمجيًا من جانب الخادم، تتكامل Pages مع Cloudflare Workers لتشغيل وظائف وخدمات الواجهة الخلفية. لمقارنة منصة Pages مع خدمات حوسبة الحافة الأخرى، اقرأ دليلنا حول مقارنة Cloudflare Pages مع Workers .

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

قبل البدء، تأكد من إعداد وتجهيز المتطلبات التالية:

  • مستودع Git على GitHub أو GitLab يحتوي على كود مشروعك (أو الملفات المبنية الجاهزة للرفع المباشر).
  • إطار عمل يخرج أصولاً ثابتة – React (Vite)، أو Vue، أو Astro، أو SvelteKit، أو Hugo، أو ملفات HTML بسيطة. وتعمل أطر العمل المعتمدة على الخادم أيضًا عبر وظائف Pages Functions.
  • بناء محلي يعمل دون أخطاء. قم بتشغيل أمر البناء الخاص بك محليًا (على سبيل المثال npm run build) وتأكد من إنشاء مجلد المخرجات بنجاح قبل ربط أي شيء بالمنصة.
  • حساب Cloudflare مجاني. لا يلزم وجود بطاقة ائتمان للاشتراك في الخطة المجانية.
  • تثبيت Node.js محليًا (موصى به) لتتمكن من محاكاة عمليات البناء واستخدام أداة Wrangler المعتمدة على سطر الأوامر.

توفر خطوة التحقق المحلي السريعة ساعات طويلة من استكشاف الأخطاء وإصلاحها؛ فإذا كان موقعك لا يبنى بشكل صحيح ونظيف على جهازك الشخصي، فلن يبنى أيضًا على خوادم Cloudflare. قم بحل المشكلات المحلية أولاً.

الخطوة 1: ربط مستودع Git الخاص بك

للبدء، قم بتسجيل الدخول إلى لوحة تحكم Cloudflare الخاصة بك، وانتقل إلى Compute > Pages، وانقر فوق Create a project.

حدد Connect to Git لربط حساب GitHub أو GitLab الخاص بك. اختر المستودع الذي يحتوي على تطبيق الويب الثابت الخاص بك. هذا التكامل ذو قيمة كبيرة لأنه ينشئ مسار تكامل مستمر (CI)؛ في كل مرة تقوم فيها بدفع كود برمجى جديد إلى فرع الإنتاج الخاص بك، تقوم Cloudflare ببناء ونشر التحديثات تلقائيًا. وبالنسبة لعمليات الدفع الأخرى على فروع التطوير، تنشئ Cloudflare روابط معاينة مؤقتة فريدة لتتمكن من مراجعة التغييرات قبل دمجها.

الخطوة 2: تكوين إعدادات البناء

تدعم Cloudflare Pages مولدات المواقع الثابتة وأطر عمل الواجهة الأمامية الشائعة. خلال مرحلة معالج الإعداد، قم بتكوين الإعدادات التالية بناءً على التقنيات التي تستخدمها:

  • أمر البناء (Build command): نص البناء البرمجي المحدد في ملف package.json الخاص بك (مثل npm run build أو hugo --minify).
  • مجلد مخرجات البناء (Build output directory): المجلد الذي يحتوي على الملفات الثابتة المجمعة والمترجمة (مثل dist أو build أو public).
  • متغيرات البيئة (Environment variables): إذا كان نص البناء البرمجي الخاص بك يتطلب مفاتيح واجهة برمجة التطبيقات (API keys) أو متغيرات تهيئة، فقم بتعريفها هنا.

تكتشف Cloudflare العديد من أطر العمل تلقائيًا، ولكن تأكيد الإعداد المسبق يتجنب فشل عملية البناء الأولى. المجموعات الشائعة هي:

إطار العملأمر البناءمجلد المخرجات
React (Vite)npm run builddist
React (Create React App)npm run buildbuild
Next.js (تصدير ثابت)npx next buildout
Astronpm run builddist
Vue (Vite)npm run builddist
SvelteKitnpm run build.svelte-kit/cloudflare
Hugohugo --minifypublic

ثبت إصدار Node الخاص بك. إن السبب الشائع لمشكلة “يعمل محليًا، ويفشل على Cloudflare” هو عدم التطابق بين إصدار Node الافتراضي الذي يستخدمه برنامج تشغيل البناء والإصدار الذي يتوقعه مشروعك. قم بالإعلان عنه صراحة، إما كمتغير بيئة في لوحة التحكم:

1NODE_VERSION = 20

أو عن طريق إضافة ملف .node-version في المجلد الرئيسي للمستودع:

120

الخطوة 3: إعداد قواعد التحويل وتخصيص الرؤوس (Headers)

بالنسبة للتطبيقات ذات الصفحة الواحدة (مثل React Router) أو عمليات ترحيل روابط URL القديمة، يجب عليك تكوين قواعد التوجيه والتحويل. وتتعامل Pages مع هذا الأمر من خلال ملفات نصية بسيطة تضعها مباشرة في مجلد المخرجات النهائي الخاص بك.

قواعد التحويل (_redirects)

قم بإنشاء ملف باسم _redirects داخل مجلدك العام (public). ولكي يتعامل تطبيق React SPA مع مسارات التوجيه من جانب العميل بشكل نظيف، أضف القاعدة الاحتياطية التالية:

1/*  /index.html  200

يجبر هذا الأمر جميع الطلبات الواردة على التوجه إلى ملف index.html الافتراضي، مما يسمح لمسار التوجيه المعتمد على JavaScript بإدارة المسار الداخلي المطلوب.

إن الترتيب مهم للغاية؛ حيث تقوم Cloudflare بتقييم القواعد من الأعلى إلى الأسفل وتتوقف عند أول مطابقة تجدها، لذا يجب أن تقع قواعد التحويل المحددة والخاصة أعلى القاعدة الاحتياطية العامة:

1# Permanent redirect for a moved page
2/old-pricing   /pricing            301
3
4# Redirect an entire section, preserving the sub-path
5/blog/*        /articles/:splat    301
6
7# SPA fallback (must come last)
8/*             /index.html         200

يقوم المتغير المخزن :splat بنقل الجزء المطابق من المسار الأصلي إلى الوجهة الجديدة. وتسمح الخطة المجانية بما يصل إلى 2,000 قاعدة تحويل ثابتة لكل مشروع؛ وإذا كنت بحاجة إلى أكثر من ذلك، انقل هذه المنطق البرمجي إلى وظيفة Pages Function أو استخدم ميزة Bulk Redirects.

الرؤوس المخصصة (_headers)

قم بإنشاء ملف باسم _headers لتطبيق قواعد الأمان، وسياسات الإحالة (Referrer-Policies)، أو عناصر التحكم المخصصة في تخزين ذاكرة التخزين المؤقت (Cache-Control):

1/*
2  X-Frame-Options: DENY
3  X-Content-Type-Options: nosniff
4  Referrer-Policy: strict-origin-when-cross-origin

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

1/assets/*
2  Cache-Control: public, max-age=31536000, immutable

لمعرفة كيف تقارن هذه القواعد مع طرق التوجيه التقليدية للواجهة الخلفية، اقرأ بناء واجهة برمجة تطبيقات خالية من السيرفرات مع Cloudflare Workers .

الخطوة 4: ربط النطاقات المخصصة

بمجرد اكتمال النشر، توفر لك منصة Cloudflare نطاقًا فرعيًا افتراضيًا للمشروع (مثل your-project.pages.dev).

ولربط نطاقك المخصص، انتقل إلى علامة التبويب Custom Domains في إعدادات مشروع Pages الخاص بك، وأدخل اسم نطاقك (مثل yourcompany.com). وإذا كان نظام DNS الخاص بك يدار بواسطة Cloudflare، فستقوم المنصة بتهيئة سجلات CNAME وتوفير شهادة SSL مجانية ومحدثة تلقائيًا على الفور. وإذا كنت بحاجة إلى مساعدة في إدارة ربط النطاقات أو DNS أو أمان خوادم موقعك، تفضل بزيارة صفحة تدقيق أمان المواقع الإلكترونية .

الخطوة 5: النشر باستخدام Wrangler CLI (الرفع المباشر)

يعد تكامل Git مناسبًا لمعظم فرق العمل، ولكن يمكنك أيضًا النشر مباشرة من جهازك المحلي أو من مسار عمل قائم باستخدام Wrangler، وهي الأداة الرسمية المعتمدة على سطر الأوامر من Cloudflare. وتكون هذه الطريقة مفيدة للغاية عندما تكون عمليات البناء تعمل بالفعل داخل بيئات GitHub Actions أو GitLab CI وتريد فقط رفع المخرجات الجاهزة والنهائية للمنصة.

قم بتثبيت Wrangler وتأكيد تسجيل الدخول:

1npm install -g wrangler
2wrangler login

قم بالبناء محليًا على جهازك، ثم ادفع مجلد المخرجات إلى المشروع المحدد:

1npm run build
2wrangler pages deploy ./dist --project-name=my-web-app

تقوم العملية الأولى بإنشاء المشروع إذا لم يكن موجودًا بالفعل. وفي بيئات التكامل المستمر (CI)، استبدل أمر تسجيل الدخول التفاعلي wrangler login برمز واجهة برمجة تطبيقات (API Token) مخصص وممرر عبر متغير بيئة، بحيث يتم إكمال الخطوات دون الحاجة لفتح المتصفح:

1# .github/workflows/deploy.yml (excerpt)
2- name: Deploy to Cloudflare Pages
3  run: npx wrangler pages deploy ./dist --project-name=my-web-app
4  env:
5    CLOUDFLARE_API_TOKEN: ${{ secrets.CLOUDFLARE_API_TOKEN }}
6    CLOUDFLARE_ACCOUNT_ID: ${{ secrets.CLOUDFLARE_ACCOUNT_ID }}

يتخطى الرفع المباشر خطوة البناء الداخلي لمنصة Cloudflare، مما يجنبك مشكلات توافق بيئة البناء ويمنحك تحكمًا كاملاً في أدوات العمل الخاصة بك.

المشكلات الشائعة واستكشاف الأخطاء وإصلاحها

تتسبب مجموعة صغيرة من المشكلات الشائعة في معظم حالات فشل النشر للمرة الأولى:

  • أخطاء 404 عند تحديث مسارات تطبيقات SPA. يرجع تحديث مسار داخلي من جانب العميل مثل /dashboard رسالة خطأ تفيد بعدم وجود ملف مطابق على القرص. ويكمن الحل في إضافة قاعدة التحويل الاحتياطية /* /index.html 200 في ملف _redirects والتأكد من نسخ هذا الملف إلى مجلد المخرجات النهائي بدلاً من بقائه في مجلد الأكواد المصدرية فقط.
  • تجاهل ملفات _redirects أو _headers. يجب أن تتواجد هذه الملفات داخل مجلد المخرجات النهائي المنشور وليس في مستودع الأكواد المصدري فقط. ومع استخدام أطر عمل مثل Vite أو Astro أو SvelteKit، ضع هذه الملفات داخل مجلد public/ (أو static/) ليقوم محرك البناء بنسخها كما هي دون تغيير.
  • نجاح البناء محليًا وفشله على Cloudflare. يحدث هذا عادةً بسبب عدم تطابق إصدار Node أو فقدان متغير بيئة مطلوب للبناء. حدد إصدار Node بدقة واعد تعريف متغيرات البيئة التي يقرأها برنامج البناء.
  • مشكلة “الملفات الكثيرة جدًا” أو تجاوز حجم النشر المسموح. يبلغ الحد الأقصى لعملية النشر الواحدة 20,000 ملف، وبحجم أقصى 25 ميجابايت للملف الواحد. يجب استضافة الوسائط والملفات الكبيرة في خدمة R2 أو خدمة استضافة صور خارجية بدلاً من تضمينها في حزمة الأكواد الثابتة للموقع.
  • ظهور أصول قديمة بعد إطلاق تحديث جديد. يمكن كش وتخزين الملفات ذات الأسماء المشفرة مثل app.4f2c.js بقوة في ذاكرة التخزين المؤقت، ولكن لا يجب معاملة ملف index.html بنفس الطريقة. احرص على إبقاء ملف HTML على كاش قصير المدة.

اعتبارات الاختبار والإنتاج

تقوم Cloudflare ببناء نشر معاينة (preview deployment) لكل فرع غير إنتاجي وكل طلب سحب (pull request)، كلٌ منها على رابط URL خاص به (على سبيل المثال abc123.my-web-app.pages.dev). ونظرًا لأن عمليات المعاينة تعمل على شبكة الحافة نفسها التي يعمل عليها موقعك المباشر، فإنها توفر مكانًا موثوقًا لمراجعة التغييرات قبل دمجها.

بالنسبة للإصدارات الفعلية، هناك بعض عناصر التحكم التي تصنع الفارق بين مجرد استضافة وسير عمل يمكن الاعتماد عليه:

  • التراجع عن الإصدارات (Rollbacks). يتم الاحتفاظ بكل عملية نشر، لذا يمكن التراجع عن إصدار معطوب عن طريق ترقية بناء سابق وإعادته إلى الإنتاج من لوحة التحكم في ثوانٍ، دون الحاجة إلى إعادة البناء.
  • فصل البيئات. حدد متغيرات مختلفة لبيئتي الإنتاج والمعاينة بحيث تشير عمليات بناء المعاينة إلى واجهات برمجة تطبيقات (APIs) التجهيز بدلاً من البيانات الحية.
  • التحليلات ومؤشرات Core Web Vitals. فعّل خدمة Cloudflare Web Analytics – التي تضع الخصوصية أولاً وتخلو من ملفات تعريف الارتباط – لتتبع قيم LCP و CLS وحركة المرور الفعلية للمستخدمين دون تحميل أي نص برمجي من طرف ثالث.
  • التحكم في الوصول إلى المعاينات. روابط المعاينة عامة بشكل افتراضي. وإذا كان أحد الفروع يكشف عن عمل لم يُطلق بعد، فضعه خلف خدمة Cloudflare Access بحيث لا يتمكن من فتحه سوى فريقك.

إن تطبيق هذه الإجراءات مبكرًا يبقي عمليات النشر لديك قابلة للتنبؤ مع نمو المشروع وزيادة عدد الأشخاص الذين يساهمون فيه.

أهم النقاط المستفادة

  • تستضيف منصة Cloudflare Pages تطبيقات الويب الثابتة على شبكة الحافة العالمية لشركة Cloudflare، مما يحسن سرعات التحميل للمستخدمين.
  • قم بأتمتة عمليات النشر من خلال ربط حسابات GitHub أو GitLab لتجميع الأكواد وبنائها تلقائيًا مع كل تعديل.
  • حدد أوامر البناء ومجلد المخرجات المتوافق بدقة مع إطار عمل موقعك (Astro أو Next.js أو Hugo أو React).
  • قم بتكوين قواعد التحويل ورؤوس الأمان المخصصة باستخدام ملفات نصية بسيطة _redirects و _headers في مجلد المخرجات النهائي.
  • اربط النطاقات المخصصة لموقعك مع شهادات SSL مجانية ومحدثة تلقائيًا وتدار بالكامل بواسطة Cloudflare.

تحسين البنية التحتية لموقعك الإلكتروني

يتطلب نشر واجهات أمامية سريعة وآمنة اختيار بنية الاستضافة وقواعد كش وتخزين الملفات الصحيحة. وتتخصص شركة Mecanik في خدمات تطوير المواقع الإلكترونية وتوفر خدمات تدقيق SEO التقني الاحترافية. ونقوم ببناء منصات React و Next.js و Astro المخصصة والمحسنة لسرعة وأداء موقعك ونشرها على Cloudflare. اتصل بنا اليوم لمناقشة مشروعك القادم.

الأسئلة الشائعة (FAQ)

ما هي استضافة Cloudflare Pages؟ هي منصة استضافة واجهة أمامية خالية من السيرفرات (serverless) تقوم ببناء وخدمة تطبيقات الويب الثابتة، وتطبيقات React SPAs، ومخرجات مولدات المواقع الثابتة (مثل Astro أو Hugo) عالميًا على شبكة CDN الخاصة بـ Cloudflare.

هل تدعم منصة Cloudflare Pages التصيير من جانب الخادم (SSR)؟ نعم، تدعم Pages أطر العمل المعتمدة على التصيير من جانب الخادم (مثل Next.js و Astro و SvelteKit) عن طريق تحويل منطق الخادم تلقائيًا إلى وظائف Cloudflare Workers خالية من السيرفرات أثناء مرحلة البناء.

كيف يمكنني تهيئة التحويلات على Cloudflare Pages؟ تقوم بإنشاء ملف نصي بسيط باسم _redirects في مجلد مخرجات البناء النهائي، وتكتب فيه قواعد إعادة التوجيه التي تحدد المسار الأصلي، والمسار المستهدف الجديد، ورمز حالة استجابة HTTP المطلوبة.

هل منصة Cloudflare Pages مجانية للاستخدام؟ نعم، تقدم Cloudflare Pages خطة مجانية سخية للغاية تتضمن عمليات نشر غير محدودة، ومعدل نقل بيانات (bandwidth) غير محدود، واستخدام النطاقات المخصصة، مما يجعلها خيارًا اقتصاديًا وممتازًا للاستضافة الثابتة.

كيف أقوم بإعداد نطاق مخصص لمشروعي على Pages؟ انتقل إلى علامة التبويب Custom Domains في لوحة تحكم مشروع Pages الخاص بك، وأدخل اسم نطاقك المطلوب، وستتولى Cloudflare تهيئة سجلات DNS وإصدار شهادة SSL مجانية لك.