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

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

ما هي الإعدادات التي يمكنك ضبطها في Hosting؟

أين يمكنك تحديد إعدادات Hosting؟

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

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

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

ترتيب أولوية Hosting ردّ

يمكن أن تتداخل أحيانًا خيارات ضبط Firebase Hosting المختلفة الموضّحة في هذه الصفحة. في حال حدوث تعارض، يحدِّد Hosting استجابته باستخدام ترتيب الأولوية التالي:

  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 Hosting. القيمة التلقائية هي دليل يحمل اسم public، ولكن يمكنك تحديد مسار أي دليل، ما دام متوفّرًا في دليل مشروعك.

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

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

  // ...
}

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

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

  // ...
}

تجاهل

اختياري
تحدّد السمة ignore الملفات التي سيتم تجاهلها عند النشر. يمكن أن يأخذ مجموعات بالطريقة نفسها التي يتعامل بها 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 Hosting محتوى صفحة 404.html المخصّصة هذه إذا أدّى أحد المتصفّحات إلى ظهور خطأ 404 Not Found في نطاقك أو نطاقك الفرعي.

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

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

حدِّد عمليات إعادة التوجيه لعناوين URL من خلال إنشاء سمة redirects تحتوي على صفيف من الكائنات (يُشار إليها باسم "قواعد إعادة التوجيه"). في كل قاعدة، حدِّد نمط عنوان URL الذي يؤدي، في حال مطابقته مع مسار عنوان URL للطلب، إلى تنشيط Hosting للردّ من خلال إعادة توجيه العميل إلى عنوان 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 Hosting قيمة source أو regex بجميع مسارات عناوين URL في بداية كل طلب (قبل أن يحدّد المتصفّح ما إذا كان هناكملف أو مجلد في هذا المسار). في حال العثور على تطابق، يُرسِل خادم المصدرFirebase Hosting استجابة إعادة توجيه HTTPS يطلب فيها من المتصفّح تقديم طلب جديد على عنوان URLdestination.

الحقل الوصف
redirects
source (إجراء مُقترَح)
أو regex

نمط عنوان URL الذي يؤدي إلى تنشيط Hosting لتطبيق إعادة التوجيه في حال تطابقه مع عنوان 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 للطلب، يؤدي إلى تنشيط Hosting للردّ كما لو تم منح الخدمة عنوان 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 Hosting قاعدة إعادة كتابة إلا إذا لم يكن هناك ملف أو دليل في مسار عنوان URL يتطابق مع نمط عنوان URL المحدد source أو regex. عندما يؤدي طلب إلى تنشيط قاعدة إعادة كتابة، يعرض المتصفّح المحتوى الفعلي لملف destination المحدّد بدلاً من إعادة توجيه HTTP.

الحقل الوصف
rewrites
source (إجراء مُقترَح)
أو regex

نمط عنوان URL الذي يؤدي إلى بدء Hosting لتطبيق إعادة الكتابة في حال مطابقته لعنوان URL للطلب الأولي

destination

ملف على الجهاز يجب أن يكون متوفّرًا

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

توجيه الطلبات إلى دالة

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

على سبيل المثال، لتوجيه جميع الطلبات من الصفحة /bigben على Hosting موقعك الإلكتروني لتنفيذ الدالة 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

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

توجيه الطلبات مباشرةً إلى حاوية Cloud Run

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

على سبيل المثال، لتوجيه جميع الطلبات من الصفحة /helloworld على موقعك الإلكترونيHosting لبدء تشغيل مثيل حاوية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 باستخدام Hosting، تكون طُرق طلب HTTP المتوافقة هي GET وPOST وHEAD وPUT وDELETE PATCH وOPTIONS. لا يمكن استخدام طرق أخرى مثل REPORT أو PROFIND.

للحصول على أفضل أداء، ضَع خدمة Cloud Run بالقرب من Hosting باستخدام المناطق التالية:

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

يمكن إعادة الكتابة من Hosting إلى 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 لإنشاء النطاق المخصّص Dynamic Links. يُرجى الانتقال إلى Dynamic Links مستندات للحصول على معلومات مفصّلة حول إعداد نطاق مخصّص لخدمة Dynamic Links.

  • استخدِم نطاقك المخصّص فقط لخدمة Dynamic Links.

    "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
      } ]
    }
  • تحديد بادئات مسارات النطاق المخصّصة لاستخدامها مع Dynamic Links

    "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
      } ]
    }

يتطلّب ضبط Dynamic Links في ملف firebase.json ما يلي:

الحقل الوصف
appAssociation

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

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

مسار تريد استخدامه في Dynamic Links

على عكس القواعد التي تعيد كتابة المسارات إلى عناوين URL، لا يمكن أن تحتوي قواعد إعادة الكتابة الخاصة بـ Dynamic Links على تعبيرات منتظمة.

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

ضبط العناوين

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

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

في ما يلي البنية الأساسية لسمة 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 الذي يؤدي إلى بدء Hosting لتطبيق العنوان المخصّص في حال تطابقه مع عنوان URL للطلب الأولي

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

صفيف من (العنصر الفرعي)headers

العناوين المخصّصة التي تطبّقها Hosting على مسار الطلب

يجب أن يتضمّن كل عنوان فرعي زوجًا من key وvalue (راجِع الصفَّين التاليين).

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

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

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

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

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

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

"hosting": {
  // ...

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

التحكّم في الشُرطات المائلة في نهاية العنوان

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

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

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

"hosting": {
  // ...

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

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

مطابقة أنماط النطاقات

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

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

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

  • * - لا تتطابق إلا مع الملفات والمجلدات في جذر دليل public

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

  • **/node_modules/**: تطابق أي ملف أو مجلد في دليل فرعي محدد مسبقًا من مجلد node_modules، والذي يمكن أن يكون هو نفسه في دليل فرعي محدد مسبقًا من دليل public.

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

مثال على الإعداد الكامل لـ Hosting

في ما يلي مثال كامل على إعدادات firebase.json لملف Firebase Hosting. يُرجى العلم أنّ ملف 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",

  }
}