تكوين سلوك الاستضافة

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

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

  • حدد الملفات الموجودة في دليل المشروع المحلي لديك والتي تريد نشرها على Firebase Hosting. تعلم كيف.

  • خدمة صفحة 404/لم يتم العثور عليها مخصصة. تعلم كيف.

  • قم بإعداد redirects للصفحات التي قمت بنقلها أو حذفها. تعلم كيف.

  • قم بإعداد rewrites لأي من هذه الأغراض:

    • عرض نفس المحتوى لعناوين URL متعددة. تعلم كيف.

    • يمكنك تقديم وظيفة أو الوصول إلى حاوية Cloud Run من عنوان URL للاستضافة. تعلم كيف: الوظيفة أو الحاوية .

    • إنشاء رابط ديناميكي للمجال المخصص. تعلم كيف.

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

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

أين تحدد تكوين الاستضافة الخاص بك؟

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

مجال وصف
rewrites
source (مستحسن)
أو regex

نمط عنوان URL، إذا كان مطابقًا لعنوان URL للطلب الأولي، فإنه يؤدي إلى تشغيل الاستضافة لتطبيق إعادة الكتابة

destination

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

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

الطلبات المباشرة إلى وظيفة

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

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

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

مثال لتكوين الاستضافة الكاملة

فيما يلي مثال كامل لتكوين 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",

  }
}