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

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

ما الذي يمكنك ضبطه في Hosting؟

  • حدِّد الملفات التي تريد نشرها في Firebase Hosting من دليل مشروعك المحلي. كيفية إجراء ذلك

  • عرض صفحة 404/لم يتم العثور على الصفحة مخصّصة كيفية إجراء ذلك

  • اضبط الرمز redirects للصفحات التي نقلتها أو حذفتها. كيفية إجراء ذلك

  • يمكنك إعداد rewrites لأي من الأغراض التالية:

  • أضِف headers لتمرير معلومات إضافية حول طلب أو رد، مثل كيفية تعامل المتصفحات مع الصفحة ومحتواها (المصادقة والتخزين المؤقت والترميز وما إلى ذلك). كيفية إجراء ذلك

  • يمكنك إعداد عمليات إعادة كتابة خاصة بالتوافق مع اللغات المختلفة (i18n) لعرض محتوى محدّد استنادًا إلى اللغة المفضّلة لدى المستخدم و/أو البلد. كيفية إجراء ذلك (صفحة مختلفة)

أين يتم تحديد إعدادات 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 التلقائية
لها الأولوية على rewrites.

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

تحديد الملفات التي سيتم نشرها

تحدّد السمات التلقائية، 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 تطلب من المتصفّح إرسال طلب جديد إلى عنوان URL destination.

الحقل الوصف
redirects
source (يُنصح به)
أو regex

نمط عنوان URL يؤدي، في حال مطابقته لعنوان URL للطلب الأوّلي، إلى تفعيل Hosting لتطبيق عملية إعادة التوجيه

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

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

لإنشاء عنوان مطابق لصفحة 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.

مطابقة نمط Glob

تستخدِم خيارات إعداد Firebase Hosting بشكل موسّع ترميز مطابقة أنماط glob مع 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",

  }
}