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

בעזרת 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 API ל-REST.

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

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

1. מרחבי שמות שמורים שמתחילים בפלח נתיב /__/*
2. הפניות שהוגדרו
3. תוכן סטטי בהתאמה מדויקת
4. כתובות URL שעברו כתיבה מחדש שהוגדרו
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

אופציונלי
המאפיין 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
  } ]
}

"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 שתואמת לדפוס כתובת ה-URL שצוין source או regex, הדפדפן יקבל במקום זאת את תוכן הקובץ בכתובת ה-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"
  } ]
}

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

שליחת בקשות ישירות לפונקציה

אפשר להשתמש ב-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

יצירת דומיין מותאם אישית 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, צריך:

הגדרת כותרות

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

כדי לציין כותרות תגובה מותאמות אישית ספציפיות לקובץ, יוצרים מאפיין 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 זמין בקטע 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 הוא 1, 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",

  }
}