הגדרת התנהגות האירוח

בעזרת Firebase Hosting תוכלו להגדיר התנהגות אירוח בהתאמה אישית לבקשות לאתר שלכם.

מה אפשר להגדיר ב-Hosting?

  • מציינים באילו קבצים בספריית הפרויקט המקומית רוצים לפרוס Firebase Hosting כך עושים את זה

  • הצגת דף מותאם אישית מסוג '404/לא נמצא'. כך עושים את זה

  • מגדירים את redirects לדפים שהעברתם או מחקת. כך עושים את זה

  • אפשר להגדיר את rewrites לכל אחת מהמטרות הבאות:

  • הוספת headers כדי להעביר הלאה מידע נוסף על בקשה או תגובה, למשל האופן שבו דפדפנים יטפלו בדף ובתוכן שלו. (אימות, שמירה במטמון, קידוד וכו'). כך עושים את זה

  • מגדירים שכתובים בינלאומיים (i18n) כדי להציג תוכן ספציפי לפי העדפת השפה ו/או המדינה של המשתמש. כך עושים זאת (באמצעות דפים שונים).

איפה מגדירים את ההגדרה של Hosting?

אתה מגדיר את התצורה של Firebase Hosting ב- קובץ firebase.json. Firebase יוצר באופן אוטומטי את הקובץ firebase.json ברמה הבסיסית (root) של הפרויקט חדשה בזמן הרצת הקוד הפקודה firebase init.

אפשר למצוא דוגמה להגדרה מלאה של firebase.json (כולל Firebase Hosting בלבד) בחלק התחתון של הדף הזה. שימו לב ש קובץ אחד (firebase.json) יכול להכיל גם הגדרות לשירותי Firebase אחרים.

אפשר לבדוק את התוכן של firebase.json שנפרס באמצעות API ל-REST ב-Hosting.

סדר העדיפות של התשובות ל-Hosting

לפעמים יש חפיפה בין אפשרויות התצורה השונות של Firebase Hosting שמתוארות בדף הזה. אם יש התנגשות, Hosting קובע את התשובה לפי סדר העדיפות הבא:

  1. מרחבי שמות שמורים שמתחילים בחלק נתיב /__/*
  2. הפניות אוטומטיות מוגדרות
  3. תוכן סטטי בהתאמה מדויקת
  4. שכתובים מוגדרים
  5. דף 404 בהתאמה אישית
  6. דף 404 שמוגדר כברירת מחדל

אם אתם משתמשים בכתובות URL שעברו כתיבה מחדש לצורך תרגום, היקף העדיפות של הטיפול בהתאמה מדויקת ובקוד 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 מציין את הקבצים שיש להתעלם מהם במהלך הפריסה. יכול להימשך 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 להשיב בהפניה אוטומטית לכתובת היעד שצוינה.

זה המבנה הבסיסי של מאפיין 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 להפניה אוטומטית, שמנחה את לדפדפן כדי לבצע בקשה חדשה בכתובת האתר destination.

שדה תיאור
redirects
source (מומלץ)
או regex

דפוס של כתובת URL, שאם הוא תואם לכתובת ה-URL של הבקשה הראשונית, מפעיל את Hosting כדי להחיל את ההפניה האוטומטית
destination

כתובת URL סטטית שבה הדפדפן צריך לשלוח בקשה חדשה

כתובת ה-URL הזו יכולה להיות נתיב יחסי או נתיב מוחלט.
type

קוד תגובת HTTPS

  • צריך להשתמש בסוג 301 בשדה 'הועבר לצמיתות'
  • צריך להשתמש בסוג של 302 בשדה 'נמצא' (הפניה זמנית)

תיעוד פלחים של כתובות URL להפניות אוטומטיות

אופציונלי
לפעמים צריך לתעד פלחים ספציפיים של דפוס כתובת ה-URL של כלל ההפניה האוטומטית (ערך source או regex), ואז לעשות שימוש חוזר בפלחים האלה בנתיב destination של הכלל.

הגדרת שכתוב

אופציונלי
אפשר להשתמש בכתיבה מחדש כדי להציג את אותו תוכן בכמה כתובות URL. שכתוב מחדש שימושי במיוחד בהתאמה לדפוס, כי אפשר לקבל כל כתובת URL שתואמת לדפוס ולתת לקוד בצד הלקוח להחליט מה להציג.

אפשר גם להשתמש בשכתובים כדי לתמוך באפליקציות PushState של HTML5 לניווט. כאשר דפדפן מנסה לפתוח נתיב של כתובת אתר שתואם שצוינו source או regex של תבנית ה-URL, הדפדפן יקבל את את התוכן של הקובץ בכתובת ה-URL destination.

מציינים שכתובים של כתובות URL על ידי יצירת מאפיין rewrites שמכיל מערך של אובייקטים (נקראים 'כללי שכתוב'). בכל כלל, מציינים תבנית של כתובת URL, שאם היא תואמת לנתיב של כתובת ה-URL של הבקשה, היא מפעילה את Hosting כדי להגיב כאילו השירות קיבל את כתובת היעד שצוינה.

זהו המבנה הבסיסי של מאפיין 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

דפוס כתובת אתר, שאם הוא תואם לכתובת האתר הראשונית של הבקשה, הוא מפעיל 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 הבאות:

כשמפנים בקשות לקונטיינרים של 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

דפוס כתובת אתר, שאם הוא תואם לכתובת האתר הראשונית של הבקשה, הוא מפעיל Hosting כדי להחיל את הכותרת המותאמת אישית

כדי ליצור כותרת שתתאים לדף 404 בהתאמה אישית, צריך להשתמש ב-404.html כערך של source או regex.

מערך של (sub-)headers

הכותרות בהתאמה אישית ש-Hosting מחילה על נתיב הבקשה

כל כותרת משנה חייבת לכלול צמד של key ו-value (עיינו בשתי השורות הבאות).

key שם הכותרת, לדוגמה Cache-Control
value ערך הכותרת, לדוגמה max-age=7200

אפשר לקרוא מידע נוסף על Cache-Control ב הקטע Hosting שמתאר הצגה של תוכן ואירוח דינמיים מיקרו-שירותים (microservices). אפשר גם לקרוא מידע נוסף על כותרות 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 משתמשות באופן נרחב התאמה של דפוסי glob סימון באמצעות extglob, בדומה לאופן שבו Git מטפל gitignore כללים וגם Bower מטפל בכללים של ignore. דף הוויקי הזה הוא מקור מידע מפורט יותר, אבל בהמשך מופיעים הסברים על הדוגמאות שנעשה בהן שימוש בדף הזה:

  • firebase.json — תואם רק לקובץ firebase.json ברמה הבסיסית (root) של הספרייה public

  • ** – מתאים לכל קובץ או תיקייה בספריית משנה שרירותית

  • * — מתאים רק קבצים ותיקיות שנמצאים ברמה הבסיסית (root) של ספריית 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",

  }
}