إعداد سلوك الاستضافة

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

ما الذي يمكنك إعداده للاستضافة؟

أين يمكنك تحديد إعدادات الاستضافة؟

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

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

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

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

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

  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 الملفات المطلوب تجاهلها عند النشر. يمكن أن يتعامل مع glob بالطريقة نفسها التي يتعامل بها 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 يتطابق مع النمط والسماح للرمز من جهة العميل بتحديد ما تريد عرضه.

يمكنك أيضًا استخدام إعادة الكتابة لإتاحة التطبيقات التي تستخدم HTML5 PushState للتنقل. عندما يحاول المتصفّح فتح مسار عنوان 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. المثال التالي هو مقتطف من عرض المحتوى الديناميكي باستخدام دوال Cloud.

على سبيل المثال، لتوجيه جميع الطلبات من صفحة /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

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

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

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

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

  • 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 توجيه عناوين URL لإزالة شرطة مائلة لاحقة.
  • في حال عدم تحديد ذلك، لا تستخدم "الاستضافة" سوى الشرطات المائلة اللاحقة لملفات فهرس الدليل (على سبيل المثال، about/index.html).

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

"hosting": {
  // ...

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

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

مطابقة أنماط الكرة الأرضية

تستفيد خيارات إعداد "استضافة Firebase" من استخدام علامة مطابقة النمط الكروي مع 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",

  }
}