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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

يمكنك التحقق من محتوى firebase.json المنشور باستخدام واجهة برمجة تطبيقات Hosting REST .

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

قد تتداخل أحيانًا خيارات تكوين استضافة 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 الملفات المطلوب تجاهلها عند النشر. يمكن أن يستغرق الأمر 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 محتوى صفحة 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
  } ]
}

"hosting": {
  // ...

  // Add the "redirects" attribute within "hosting"
  "redirects": [ {
    // Returns a permanent redirect to "/bar" for requests to "/foo" (but not "/foo/**")
    "source": "/foo",
    "destination": "/bar",
    "type": 301
  }, {
    // Returns a permanent redirect to "/bar" for requests to both "/foo" and "/foo/**"
    "source": "/foo{,/**}"
    "destination": "/bar"
    "type": 301
  }, {
    // Returns a temporary redirect for all requests to files or directories in the "firebase" directory
    "source": "/firebase/**",
    "destination": "https://firebase.google.com/",
    "type": 302
  }, {
    // A regular expression-based redirect equivalent to the above behavior
    "regex": "/firebase/.*",
    "destination": "https://firebase.google.com/",
    "type": 302
  } ]
}

تحتوي سمة redirects على مصفوفة من قواعد إعادة التوجيه ، حيث يجب أن تتضمن كل قاعدة الحقول الموجودة في الجدول أدناه.

يقارن Firebase Hosting قيمة source أو regex مقابل جميع مسارات URL في بداية كل طلب (قبل أن يحدد المتصفح ما إذا كان الملف أو المجلد موجودًا في ذلك المسار). إذا تم العثور على تطابق ، فإن خادم أصل Firebase Hosting يرسل استجابة إعادة توجيه HTTPS تخبر المتصفح بتقديم طلب جديد على عنوان URL destination .

التقاط مقاطع عناوين URL لعمليات إعادة التوجيه

خياري
في بعض الأحيان ، قد تحتاج إلى التقاط شرائح معينة من نمط عنوان URL لقاعدة إعادة التوجيه (قيمة source أو regex ) ، ثم إعادة استخدام هذه الأجزاء في مسار destination القاعدة.

"hosting": {
  // ...

  "redirects": [ {
    "source": "/blog/:post*",  // captures the entire URL segment beginning at "post"
    "destination": "https://blog.myapp.com/:post", // includes the entire URL segment identified and captured by the "source" value
    "type": 301
  }, {
    "source": "/users/:id/profile",  // captures only the URL segment "id", but nothing following
    "destination": "/users/:id/newProfile",  // includes the URL segment identified and captured by the "source" value
    "type": 301
  } ]
}

"hosting": {
  // ...

  "redirects": [ {
    "regex": "/blog/(?P<post>.+)",  // if you're familiar with PCRE, be aware that RE2 requires named capture groups to begin with ?P
    "destination": "https://blog.myapp.com/:post",  // includes the entire URL segment identified and captured by the `regex` value
    "type": 301
  }, {
    "regex": "/users/(\d+)/profile",  // uses the \d directive to only match numerical path segments
    "destination": "/users/:1/newProfile",  // the first capture group to be seen in the `regex` value is named 1, and so on
    "type": 301
  } ]
}

تكوين عمليات إعادة الكتابة

خياري
استخدم إعادة الكتابة لإظهار نفس المحتوى لعناوين 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"
  } ]
}

"hosting": {
// ...

// Add the "rewrites" attribute within "hosting"
"rewrites": [ {
  // Serves index.html for requests to files or directories that do not exist
  "source": "**",
  "destination": "/index.html"
}, {
  // Serves index.html for requests to both "/foo" and "/foo/**"
  // Using "/foo/**" only matches paths like "/foo/xyz", but not "/foo"
  "source": "/foo{,/**}",
  "destination": "/index.html"
}, {
  // A regular expression-based rewrite equivalent to the above behavior
  "regex": "/foo(/.*)?",
  "destination": "/index.html"
}, {
  // Excludes specified pathways from rewrites
  "source": "!/@(js|css)/**",
  "destination": "/index.html"
} ]
}

تحتوي خاصية rewrites على مجموعة من قواعد إعادة الكتابة ، حيث يجب أن تتضمن كل قاعدة الحقول الموجودة في الجدول أدناه.

يطبق Firebase Hosting قاعدة إعادة الكتابة فقط في حالة عدم وجود ملف أو دليل في مسار عنوان URL يطابق source المحدد أو نمط عنوان URL regex . عندما يقوم أحد الطلبات بتشغيل قاعدة إعادة الكتابة ، يقوم المتصفح بإرجاع المحتوى الفعلي لملف destination المحدد بدلاً من إعادة توجيه HTTP.

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

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

على سبيل المثال ، لتوجيه جميع الطلبات من الصفحة /bigben على موقع الاستضافة الخاص بك لتنفيذ وظيفة bigben :

"hosting": {
  // ...

  // Directs all requests from the page `/bigben` to execute the `bigben` function
  "rewrites": [ {
    "source": "/bigben",
    "function": "bigben",
    "region": "us-central1"  // 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 مع الاستضافة في المناطق التالية:

• asia-east1
• asia-east2
• asia-northeast1
• asia-northeast2
• asia-northeast3
• asia-south1
• asia-southeast1
• asia-southeast2
• australia-southeast1
• europe-north1
• europe-west1
• europe-west2
• europe-west3
• europe-west4
• europe-west6
• northamerica-northeast1
• southamerica-east1
• us-central1
• us-east1
• us-east4
• us-west1

إنشاء روابط ديناميكية للمجال المخصص

يمكنك استخدام rewrites لإنشاء روابط ديناميكية للمجال المخصص. قم بزيارة وثائق 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
    } ]
  }
  

• حدد بادئات مسار المجال المخصص لاستخدامها للارتباطات الديناميكية

  "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 ما يلي:

تكوين الرؤوس

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

حدد رؤوس استجابة مخصصة خاصة بالملف عن طريق إنشاء سمة 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": "*"
    } ]
  } ]
}

"hosting": {
  // ...

  // Add the "headers" attribute within "hosting"
  "headers": [ {
    // Applies a CORS header for all font files
    "source": "**/*.@(eot|otf|ttf|ttc|woff|font.css)",
    "headers": [ {
      "key": "Access-Control-Allow-Origin",
      "value": "*"
    } ]
  }, {
    // Overrides the default 1 hour browser cache with a 2 hour cache for all image files
    "source": "**/*.@(jpg|jpeg|gif|png)",
    "headers": [ {
      "key": "Cache-Control",
      "value": "max-age=7200"
    } ]
  }, {
    // A regular expression-based rewrite equivalent to the above behavior
    "regex": ".+/\w+\.(jpg|jpeg|gif|png)$",
    "headers": [ {
      "key": "Cache-Control",
      "value": "max-age=7200"
    } ]
  }, {
    // Sets the cache header for 404 pages to cache for 5 minutes
    "source": "404.html",
    "headers": [ {
      "key": "Cache-Control",
      "value": "max-age=300"
    } ]
  } ]
}

تحتوي السمة headers على مجموعة من التعريفات ، حيث يجب أن يتضمن كل تعريف الحقول الموجودة في الجدول أدناه.

يمكنك معرفة المزيد حول 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 ignore Bower القواعد. تعد صفحة 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",

  }
}