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

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

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

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

أنت تحدد إعدادات Firebase Hosting في ملف firebase.json. الإعداد عن بُعد ينشئ ملف 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 الملفات المراد تجاهلها عند النشر. قد يستغرق 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 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 يطابق النمط والسماح للرمز البرمجي من جهة العميل بتحديد ما يجب عرضه.

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

تتوفر إعادة الكتابة إلى 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 لإنشاء النطاق المخصّص 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.

مصفوفة (sub-)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 من مطابقة أنماط الكرة الأرضية بترميز 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

مثال على إعداد 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",

  }
}