ضبط سلوك الاستضافة

من خلال "استضافة Firebase"، يمكنك ضبط سلوك الاستضافة المخصّصة للطلبات التي تصل إلى موقعك الإلكتروني.

ما الذي يمكنك تهيئته للاستضافة؟

أين يمكنك تحديد تهيئة الاستضافة؟

تحدد إعدادات استضافة Firebase في ملف firebase.json. ينشئ Firebase ملف firebase.json تلقائيًا في جذر دليل مشروعك عند تشغيل الأمر firebase init.

يمكنك العثور على مثال كامل على إعداد firebase.json (يغطّي "استضافة Firebase" فقط) في أسفل هذه الصفحة. يُرجى العلم بأنّ ملف firebase.json يمكن أن يحتوي أيضًا على عمليات ضبط لخدمات Firebase الأخرى.

يمكنك الاطّلاع على محتوى firebase.json الذي تم نشره باستخدام Hosting REST API.

ترتيب أولوية استضافة الردود

يمكن أن تتداخل أحيانًا خيارات الإعداد المختلفة الموضّحة في هذه الصفحة. إذا كان هناك تعارض، تحدد خدمة الاستضافة ردها باستخدام ترتيب الأولوية التالي:

  1. مساحات الاسم المحجوزة التي تبدأ بمقطع مسار /__/*
  2. عمليات إعادة التوجيه التي تمّ ضبطها
  3. محتوى ثابت بمطابقة تامة
  4. تم ضبط عمليات إعادة الكتابة.
  5. صفحة 404 مخصّصة
  6. صفحة 404 التلقائية

إذا كنت تستخدم إعادة كتابة i18n، سيتم توسيع نطاق ترتيب المطابقة التامة وأولوية معالجة 404 لاستيعاب "محتوى i18n".

تحديد الملفات المطلوب نشرها

إنّ السمتَين التلقائيتَين، public وignore، والمضمّنتان في ملف firebase.json التلقائي، تحدّدان الملفات في دليل المشروع التي يجب نشرها في مشروع Firebase.

تظهر إعدادات hosting التلقائية في ملف firebase.json على النحو التالي:

"hosting": {
  "public": "public",  // the only required attribute for Hosting
  "ignore": [
    "firebase.json",
    "**/.*",
    "**/node_modules/**"
  ]
}

علنية

مطلوبة
تحدّد السمة public الدليل المطلوب نشره في "استضافة Firebase". والقيمة التلقائية هي دليل يُسمى public ولكن يمكنك تحديد مسار أي دليل ما دام متوفرًا في دليل مشروعك.

في ما يلي الاسم المحدّد التلقائي للدليل المطلوب نشره:

"hosting": {
  "public": "public"

  // ...
}

يمكنك تغيير القيمة التلقائية للدليل الذي تريد نشره:

"hosting": {
  "public": "dist/app"

  // ...
}

تجاهل

اختيارية
تحدد السمة ignore الملفات التي سيتم تجاهلها عند النشر. ويمكن أن تتعامل مع globs بالطريقة نفسها التي تتعامل بها Git مع .gitignore.

في ما يلي القيم التلقائية للملفات التي سيتم تجاهلها:

"hosting": {
  // ...

  "ignore": [
    "firebase.json",  // the Firebase configuration file (the file described on this page)
    "**/.*",  // files with a leading period should be hidden from the system
    "**/node_modules/**"  // contains dependencies used to create your site but not run it
  ]
}

تخصيص صفحة 404/لم يتم العثور على الصفحة

اختياري
يمكنك عرض خطأ 404 Not Found مخصّص عندما يحاول المستخدم الوصول إلى صفحة غير متوفّرة.

أنشئ ملفًا جديدًا في دليل public لمشروعك، وحدِّد اسمه 404.html، ثم أضِف محتوى 404 Not Found المخصّص إلى الملف.

ستعرض "استضافة Firebase" محتوى صفحة 404.html المخصّصة هذه إذا أظهر المتصفّح خطأ 404 Not Found على نطاقك أو نطاقك الفرعي.

ضبط عمليات إعادة التوجيه

اختياري
يمكنك استخدام إعادة توجيه عنوان URL لمنع الروابط المعطلة في حال نقل صفحة أو لتقصير عناوين URL. على سبيل المثال، يمكنك إعادة توجيه متصفح من example.com/team إلى example.com/about.html.

حدِّد عمليات إعادة توجيه عناوين URL من خلال إنشاء سمة redirects تحتوي على مجموعة من العناصر (تُسمّى "قواعد إعادة التوجيه"). في كل قاعدة، حدِّد نمطًا لعنوان URL يؤدي إلى استجابة "الاستضافة" بإعادة التوجيه إلى عنوان URL المقصود المحدّد، في حال تطابقه مع مسار عنوان URL للطلب.

في ما يلي البنية الأساسية للسمة redirects. في هذا المثال، تتم إعادة توجيه الطلبات إلى /foo من خلال تقديم طلب جديد إلى /bar.

"hosting": {
  // ...

  // Returns a permanent redirect to "/bar" for requests to "/foo" (but not "/foo/**")
  "redirects": [ {
    "source": "/foo",
    "destination": "/bar",
    "type": 301
  } ]
}

تحتوي السمة redirects على مصفوفة من قواعد إعادة التوجيه، حيث يجب أن تتضمن كل قاعدة الحقول الواردة في الجدول أدناه.

تقارن ميزة "استضافة Firebase" القيمة source أو regex بجميع مسارات عناوين URL في بداية كل طلب (قبل أن يحدِّد المتصفّح ما إذا كان هناك ملف أو مجلد في ذلك المسار). إذا تم العثور على مطابقة، يرسل خادم المصدر "استضافة Firebase" استجابة لإعادة التوجيه HTTPS تطلب من المتصفّح تقديم طلب جديد على عنوان URL destination.

الحقل الوصف
redirects
source (سمة مقترَحة)
أو regex

يشير هذا المصطلح إلى نمط عنوان URL يؤدي إلى تشغيل خدمة "الاستضافة" في حال تطابُقه مع عنوان URL للطلب الأولي.

destination

يشير هذا المصطلح إلى عنوان URL ثابت يجب أن يقدّم فيه المتصفّح طلبًا جديدًا.

ويمكن أن يكون عنوان URL هذا مسارًا نسبيًا أو مسارًا مطلقًا.

type

رمز استجابة HTTPS

  • استخدام نوع 301 بعبارة "يتم النقل نهائيًا"
  • استخدام نوع 302 لعبارة "تم العثور عليها" (إعادة توجيه مؤقتة)

تسجيل شرائح عناوين URL لعمليات إعادة التوجيه

اختيارية
في بعض الأحيان، قد تحتاج إلى تسجيل مقاطع معيّنة من نمط عنوان URL لقاعدة إعادة التوجيه (القيمة source أو regex)، ثم إعادة استخدام هذه الشرائح في مسار destination للقاعدة.

ضبط عمليات إعادة الكتابة

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

يمكنك أيضًا استخدام عمليات إعادة الكتابة لدعم التطبيقات التي تستخدم HTML5pushState للتنقّل. عندما يحاول المتصفّح فتح مسار عنوان URL يتطابق مع نمط عنوان URL المحدّد للسمة source أو regex، سيتم منح المتصفّح محتوى الملف على عنوان URL destination بدلاً من ذلك.

حدِّد عمليات إعادة كتابة عنوان URL من خلال إنشاء سمة rewrites تحتوي على مجموعة من العناصر (تُسمّى "قواعد إعادة الكتابة"). في كل قاعدة، حدد نمط عنوان URL يؤدي إلى تشغيل "الاستضافة" إذا تم مطابقته مع مسار عنوان URL للطلب كما لو تم منح الخدمة عنوان URL المقصود المحدد.

في ما يلي البنية الأساسية للسمة rewrites. يعرض هذا المثال index.html لطلبات الملفات أو الأدلة غير الموجودة.

"hosting": {
  // ...

  // Serves index.html for requests to files or directories that do not exist
  "rewrites": [ {
    "source": "**",
    "destination": "/index.html"
  } ]
}

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

لا تطبّق "استضافة Firebase" قاعدة إعادة الكتابة إلا في حال عدم توفّر الملف أو الدليل في مسار عنوان URL الذي يتطابق مع نمط عنوان URL المحدَّد للرمز source أو regex. عندما يشغّل طلب قاعدة إعادة الكتابة، يعرض المتصفّح المحتوى الفعلي من ملف destination المحدّد بدلاً من إعادة توجيه HTTP.

الحقل الوصف
rewrites
source (سمة مقترَحة)
أو regex

يشير هذا المصطلح إلى نمط عنوان URL يؤدي إلى تشغيل خدمة "الاستضافة" في حال تطابُقه مع عنوان URL للطلب الأولي.

destination

ملف محلي يجب أن يكون موجودًا

ويمكن أن يكون عنوان URL هذا مسارًا نسبيًا أو مسارًا مطلقًا.

الطلبات المباشرة للدالة

يمكنك استخدام rewrites لعرض دالة من "عنوان URL لاستضافة Firebase". المثال التالي هو مقتطف من عرض محتوى ديناميكي باستخدام دوال السحابة.

على سبيل المثال، لتوجيه جميع الطلبات من الصفحة /bigben على "موقع الاستضافة الإلكتروني" لتنفيذ دالة bigben:

"hosting": {
  // ...

  // Directs all requests from the page `/bigben` to execute the `bigben` function
  "rewrites": [ {
    "source": "/bigben",
    "function": {
      "functionId": "bigben",
      "region": "us-central1"  // optional (see note below)
      "pinTag": true           // optional (see note below)
    }
  } ]
}

بعد إضافة قاعدة إعادة الكتابة هذه والنشر على Firebase (باستخدام firebase deploy)، يمكن الوصول إلى وظيفتك من خلال عناوين URL التالية:

  • نطاقاتك الفرعية في Firebase:
    PROJECT_ID.web.app/bigben و PROJECT_ID.firebaseapp.com/bigben

  • أيّ نطاقات مخصّصة مرتبطة:
    CUSTOM_DOMAIN/bigben

عند إعادة توجيه الطلبات إلى الدوال باستخدام ميزة "الاستضافة"، تكون طرق طلبات HTTP المتوافقة هي GET وPOST وHEAD وPUT وDELETE وPATCH وOPTIONS. ولا تتوفّر طرق أخرى، مثل REPORT أو PROFIND.

الطلبات المباشرة لحاوية Cloud Run

يمكنك استخدام "rewrites" للوصول إلى حاوية Cloud Run من عنوان URL لـ "استضافة Firebase". المثال التالي هو مقتطف من عرض محتوى ديناميكي باستخدام Cloud Run.

على سبيل المثال، لتوجيه جميع الطلبات من الصفحة /helloworld على "موقع الاستضافة الإلكتروني" الخاص بك لبدء تشغيل مثيل حاوية helloworld وتشغيله:

"hosting": {
 // ...

 // Directs all requests from the page `/helloworld` to trigger and run a `helloworld` container
 "rewrites": [ {
   "source": "/helloworld",
   "run": {
     "serviceId": "helloworld",  // "service name" (from when you deployed the container image)
     "region": "us-central1"  // optional (if omitted, default is us-central1)
   }
 } ]
}

بعد إضافة قاعدة إعادة الكتابة هذه والنشر على Firebase (باستخدام firebase deploy)، يمكن الوصول إلى صورة الحاوية عن طريق عناوين URL التالية:

  • نطاقاتك الفرعية في Firebase:
    PROJECT_ID.web.app/helloworld و PROJECT_ID.firebaseapp.com/helloworld

  • أيّ نطاقات مخصّصة مرتبطة:
    CUSTOM_DOMAIN/helloworld

عند إعادة توجيه الطلبات إلى حاويات Cloud Run من خلال ميزة "الاستضافة"، تكون طرق طلبات HTTP المتوافقة هي GET وPOST وHEAD وPUT وDELETE وPATCH وOPTIONS. وهناك طرق أخرى، مثل REPORT أو PROFIND، غير متوافقة.

للحصول على أفضل أداء، يمكنك تجميع خدمة Cloud Run مع ميزة "الاستضافة" باستخدام المناطق التالية:

  • us-west1
  • us-central1
  • us-east1
  • europe-west1
  • asia-east1

تتوفر عمليات إعادة الكتابة إلى Cloud Run من "الاستضافة" في المناطق التالية:

  • asia-east1
  • asia-east2
  • asia-northeast1
  • asia-northeast2
  • asia-northeast3
  • asia-south1
  • asia-south2
  • asia-southeast1
  • asia-southeast2
  • australia-southeast1
  • australia-southeast2
  • europe-central2
  • europe-north1
  • europe-southwest1
  • europe-west1
  • europe-west12
  • europe-west2
  • europe-west3
  • europe-west4
  • europe-west6
  • europe-west8
  • europe-west9
  • me-central1
  • me-west1
  • northamerica-northeast1
  • northamerica-northeast2
  • southamerica-east1
  • southamerica-west1
  • us-central1
  • us-east1
  • us-east4
  • us-east5
  • us-south1
  • us-west1
  • us-west2
  • us-west3
  • us-west4
  • us-west1
  • us-central1
  • us-east1
  • europe-west1
  • asia-east1

يمكنك استخدام rewrites لإنشاء روابط ديناميكية لنطاق خاص. انتقِل إلى وثائق الروابط الديناميكية للحصول على معلومات تفصيلية حول إعداد نطاق خاص للروابط الديناميكية.

  • استخدام النطاق الخاص فقط للروابط الديناميكية

    "hosting": {
      // ...
    
      "appAssociation": "AUTO",  // required for Dynamic Links (default is AUTO if not specified)
    
      // Add the "rewrites" attribute within "hosting"
      "rewrites": [ {
        "source": "/**",  // the Dynamic Links start with "https://CUSTOM_DOMAIN/"
        "dynamicLinks": true
      } ]
    }
    
  • تحديد بادئات مسارات النطاق المخصّصة لاستخدامها في الروابط الديناميكية

    "hosting": {
      // ...
    
      "appAssociation": "AUTO",  // required for Dynamic Links (default is AUTO if not specified)
    
      // Add the "rewrites" attribute within "hosting"
      "rewrites": [ {
        "source": "/promos/**",  // the Dynamic Links start with "https://CUSTOM_DOMAIN/promos/"
        "dynamicLinks": true
      }, {
        "source": "/links/share/**",  // the Dynamic Links start with "https://CUSTOM_DOMAIN/links/share/"
        "dynamicLinks": true
      } ]
    }
    

يتطلب إعداد الروابط الديناميكية في ملف firebase.json ما يلي:

الحقل الوصف
appAssociation

يجب ضبطها على AUTO.

  • إذا لم تضمّن هذه السمة في الإعدادات، ستكون القيمة التلقائية للسمة appAssociation هي AUTO.
  • من خلال ضبط هذه السمة على AUTO، يمكن لخدمة الاستضافة إنشاء ملفات assetlinks.json وapple-app-site-association ديناميكيًا عند طلبها.
rewrites
source

مسار تريد استخدامه للروابط الديناميكية

على عكس القواعد التي تعيد كتابة المسارات إلى عناوين URL، لا يمكن أن تحتوي قواعد إعادة كتابة الروابط الديناميكية على تعبيرات عادية.

dynamicLinks يجب ضبطها على true.

إعداد العناوين

اختيارية
تسمح العناوين للعميل والخادم بتمرير معلومات إضافية مع طلب أو ردّ. يمكن أن تؤثر بعض مجموعات العناوين في كيفية تعامل المتصفح مع الصفحة ومحتواها، بما في ذلك التحكم في الوصول والمصادقة والتخزين المؤقت والترميز.

حدِّد عناوين استجابة مخصّصة وخاصة بالملف من خلال إنشاء سمة headers تحتوي على مصفوفة من عناصر العناوين. في كل كائن، حدد نمط عنوان URL يؤدي إلى تشغيل "الاستضافة" إذا تطابقت مع مسار عنوان URL للطلب لتطبيق عناوين الاستجابة المخصصة المحددة.

في ما يلي البنية الأساسية للسمة headers. يطبق هذا المثال عنوان CORS لجميع ملفات الخطوط.

"hosting": {
  // ...

  // Applies a CORS header for all font files
  "headers": [ {
    "source": "**/*.@(eot|otf|ttf|ttc|woff|font.css)",
    "headers": [ {
      "key": "Access-Control-Allow-Origin",
      "value": "*"
    } ]
  } ]
}

تحتوي السمة headers على مصفوفة من التعريفات، حيث يجب أن يتضمّن كل تعريف الحقول في الجدول أدناه.

الحقل الوصف
headers
source (سمة مقترَحة)
أو regex

نمط عنوان URL، في حال تطابُقه مع عنوان URL للطلب الأولي، يؤدي إلى تشغيل "الاستضافة" لتطبيق العنوان المخصّص.

لإنشاء عنوان من أجل مطابقته مع صفحة 404 المخصّصة، استخدِم 404.html كقيمة source أو regex.

مصفوفة الدالة (sub-)headers

العناوين المخصّصة التي تنطبق عليها ميزة "الاستضافة" على مسار الطلب

يجب أن يشتمل كل عنوان فرعي على زوج key وvalue (راجِع الصفين التاليين).

key اسم العنوان، على سبيل المثال Cache-Control
value قيمة العنوان، على سبيل المثال max-age=7200

يمكنك معرفة المزيد من المعلومات عن Cache-Control في قسم "الاستضافة" الذي يصف عرض المحتوى الديناميكي واستضافة الخدمات المصغّرة. يمكنك أيضًا معرفة المزيد من المعلومات عن عناوين CORS.

التحكّم في إضافات ".html"

اختيارية
تتيح لك السمة cleanUrls التحكم في ما إذا كان يجب أن تتضمن عناوين URL الإضافة .html أم لا.

عند استخدام true، تعمل ميزة "الاستضافة" على إسقاط الإضافة .html تلقائيًا من عناوين URL للملفات المحمَّلة. وإذا تم إدراج إضافة .html في الطلب، تُجري ميزة "الاستضافة" عملية إعادة توجيه 301 إلى المسار نفسه، ولكن سيتم استبعاد الإضافة .html.

إليك طريقة التحكّم في تضمين .html في عناوين URL من خلال تضمين سمة cleanUrls:

"hosting": {
  // ...

  // Drops `.html` from uploaded URLs
  "cleanUrls": true
}

التحكّم في الشرطات المائلة اللاحقة

اختيارية
تسمح لك السمة trailingSlash بالتحكّم في ما إذا كان يجب أن تتضمّن عناوين URL للمحتوى الثابت شرطات مائلة لاحقة أم لا.

  • عند true، تعيد خدمة الاستضافة توجيه عناوين URL لإضافة شرطة مائلة لاحقة.
  • عند false، تعيد خدمة الاستضافة توجيه عناوين URL لإزالة شرطة مائلة لاحقة.
  • في حال عدم تحديد خيار "الاستضافة"، لا تستخدم خدمة Hosting إلا الشرطة المائلة اللاحقة لملفات فهرس الدليل (مثل about/index.html).

إليك كيفية التحكّم في الشرطة المائلة اللاحقة عن طريق إضافة سمة trailingSlash:

"hosting": {
  // ...

  // Removes trailing slashes from URLs
  "trailingSlash": false
}

لا تؤثر السمة trailingSlash في عمليات إعادة كتابة المحتوى الديناميكي الذي تعرضه دوال Cloud أو Cloud Run.

مطابقة نمط Glob

تستفيد خيارات ضبط "استضافة Firebase" بشكل كبير من ترميز مطابقة النمط glob مع extglob، على غرار طريقة معالجة قواعد Git قواعد gitignore وكيفية معالجة Bower لقواعد ignore. تمثّل صفحة wiki هذه مرجعًا أكثر تفصيلاً، ولكن في ما يلي تفسيرات للأمثلة المستخدمة في هذه الصفحة:

  • firebase.json: يتطابق مع ملف firebase.json في جذر الدليل public فقط.

  • **: مطابقة أي ملف أو مجلد في دليل فرعي عشوائي

  • *: تتم مطابقة الملفات والمجلدات في جذر الدليل public فقط.

  • **/.*: يتطابق مع أي ملف يبدأ بـ . (عادةً الملفات المخفية، كما هو الحال في المجلد .git) في دليل فرعي عشوائي

  • **/node_modules/**: يطابق أي ملف أو مجلد في دليل فرعي فرعي ضمن مجلد node_modules، والذي يمكن أن يكون ضمن دليل فرعي عشوائي ضمن دليل public

  • **/*.@(jpg|jpeg|gif|png): يتطابق مع أي ملف في دليل فرعي فرعي ينتهي بأحد العناصر التالية بالضبط: .jpg أو .jpeg أو .gif أو .png

مثال على إعداد الاستضافة الكامل

في ما يلي مثال كامل على إعداد firebase.json لاستضافة Firebase. تجدر الإشارة إلى أنّ ملف firebase.json يمكن أن يحتوي أيضًا على عمليات ضبط لخدمات Firebase الأخرى.

{
  "hosting": {

    "public": "dist/app",  // "public" is the only required attribute for Hosting

    "ignore": [
      "firebase.json",
      "**/.*",
      "**/node_modules/**"
    ],

    "redirects": [ {
      "source": "/foo",
      "destination": "/bar",
      "type": 301
    }, {
      "source": "/firebase/**",
      "destination": "https://www.firebase.com",
      "type": 302
    } ],

    "rewrites": [ {
      // Shows the same content for multiple URLs
      "source": "/app/**",
      "destination": "/app/index.html"
    }, {
      // Configures a custom domain for Dynamic Links
      "source": "/promos/**",
      "dynamicLinks": true
    }, {
      // Directs a request to Cloud Functions
      "source": "/bigben",
      "function": "bigben"
    }, {
      // Directs a request to a Cloud Run containerized app
      "source": "/helloworld",
      "run": {
        "serviceId": "helloworld",
        "region": "us-central1"
      }
    } ],

    "headers": [ {
      "source": "**/*.@(eot|otf|ttf|ttc|woff|font.css)",
      "headers": [ {
        "key": "Access-Control-Allow-Origin",
        "value": "*"
      } ]
    }, {
      "source": "**/*.@(jpg|jpeg|gif|png)",
      "headers": [ {
        "key": "Cache-Control",
        "value": "max-age=7200"
      } ]
    }, {
      "source": "404.html",
      "headers": [ {
        "key": "Cache-Control",
        "value": "max-age=300"
      } ]
    } ],

    "cleanUrls": true,

    "trailingSlash": false,

    // Required to configure custom domains for Dynamic Links
    "appAssociation": "AUTO",

  }
}