باستخدام Firebase Hosting، يمكنك ضبط سلوك استضافة مخصّص للطلبات الموجّهة إلى موقعك الإلكتروني.
ما الذي يمكنك ضبطه في Hosting؟
حدِّد الملفات التي تريد نشرها في Firebase Hosting من دليل مشروعك المحلي. كيفية إجراء ذلك
عرض صفحة 404/لم يتم العثور على الصفحة مخصّصة كيفية إجراء ذلك
اضبط الرمز
redirects
للصفحات التي نقلتها أو حذفتها. كيفية إجراء ذلكيمكنك إعداد
rewrites
لأي من الأغراض التالية:عرض المحتوى نفسه لعدة عناوين URL: كيفية إجراء ذلك
عرض وظيفة أو الوصول إلى حاوية Cloud Run من عنوان URL Hosting تعرَّف على كيفية إجراء ذلك: دالة أو حاوية.
إنشاء نطاق خاص Dynamic Link كيفية إجراء ذلك
أضِف
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 استجابته باستخدام ترتيب الأولوية التالي:
- مساحات الأسماء المحجوزة التي تبدأ بشريحة مسار
/__/*
- عمليات إعادة التوجيه التي تم إعدادها
- المحتوى الثابت الذي يتضمّن تطابقًا تامًا
- عمليات إعادة الكتابة التي تم ضبطها
- صفحة 404 مخصّصة
- صفحة 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
|
تسجيل أجزاء من عناوين 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
إنشاء نطاق خاص Dynamic Links
يمكنك استخدام 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 |
يجب ضبطها على
|
|
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 المخصّصة، استخدِم |
||
مصفوفة من (عناصر فرعية)headers |
العناوين المخصّصة التي تنطبق على مسار الطلبHosting يجب أن يتضمّن كل عنوان فرعي
زوجًا من |
||
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",
}
}