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

בעזרת 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 שנפרס באמצעות API ל-REST ב-Hosting.

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

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

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

אופציונלי
המאפיין 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. אי אפשר להשתמש ב-methods אחרות כמו 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, 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 ברמה הבסיסית של הספרייה 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",

  }
}