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

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

אילו הגדרות אפשר לקבוע עבור Hosting?

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

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

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

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

  • הצגת אותו תוכן בכמה כתובות URL. איך עושים את זה

  • הצגת פונקציה או גישה לקונטיינר Cloud Run מכתובת URL Hosting פונקציה או מאגר תגים.

  • יצירת דומיין מותאם אישית Dynamic Link. כך עושים את זה

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

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

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

מגדירים את התצורה של Firebase Hosting בקובץ firebase.json. כשמריצים את הפקודה firebase init, מערכת Firebase יוצרת אוטומטית את הקובץ firebase.json בספריית הבסיס של הפרויקט.

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

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

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

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

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

אופציונלי
המאפיין ignore מציין את הקבצים שצריך להתעלם מהם במהלך הפריסה. אפשר להשתמש בתבניות glob בדיוק כמו ש-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 שתואם ל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"
  } ]
}

"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 באתר שלכם לביצוע הפונקציה bigben:Hosting

"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, צריך:

הגדרת כותרות

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

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

כשמעלים קובץ עם סיומת .html,‏ true,‏ Hosting מסיר את הסיומת .html מכתובות ה-URL של הקובץ באופן אוטומטי. אם מוסיפים סיומת .html לבקשה,‏ Hosting מבצע הפניה אוטומטית 301 לאותו נתיב, אבל בלי הסיומת .html.

כדי לשלוט בהכללה של .html בכתובות URL, צריך לכלול מאפיין cleanUrls:

"hosting": {
  // ...

  // Drops `.html` from uploaded URLs
  "cleanUrls": true
}

שליטה בלוכסנים בסוף כתובת URL

אופציונלי
המאפיין trailingSlash מאפשר לקבוע אם כתובות URL של תוכן סטטי צריכות לכלול קווים נטויים בסוף.

• כשמפעילים את true, Hosting מפנה כתובות URL כדי להוסיף קו נטוי בסוף.
• כשמשתמשים ב-false, Hosting כתובות URL מופנות אוטומטית כדי להסיר קו נטוי בסוף.
• אם לא מציינים, Hosting משתמש רק בלוכסנים בסוף כתובת URL לקובצי אינדקס של ספריות (לדוגמה, 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",

  }
}