設定託管行為

透過集合功能整理內容 你可以依據偏好儲存及分類內容。

使用 Firebase Hosting 時，您可以為網站的要求設定自訂代管行為。

您可以為 Hosting 設定哪些項目？

• 指定要部署至 Firebase Hosting 的本機專案目錄中的檔案。瞭解詳情。

• 提供自訂的 404/找不到頁面。瞭解詳情。

• 針對已移動或刪除的網頁設定 redirects。瞭解詳情。

• 設定 rewrites 以用於下列任一用途：

  • 透過多個網址顯示相同內容。瞭解如何操作。

  • 透過 Hosting 網址提供函式或存取 Cloud Run 容器。瞭解如何：函式或容器。

  • 建立自訂網域 Dynamic Link。瞭解詳情。

• 新增 headers 可傳遞有關要求或回應的額外資訊，例如瀏覽器應如何處理網頁及其內容 (驗證、快取、編碼等)。瞭解詳情。

• 設定國際化 (i18n) 重寫功能，根據使用者的語言偏好和/或國家/地區，提供特定內容。瞭解如何 (不同頁面)。

您在何處定義 Hosting 設定？

您可以在 firebase.json 檔案中定義 Firebase Hosting 設定。執行 firebase init 指令時，Firebase 會自動在專案目錄的根目錄中建立 firebase.json 檔案。

您可以在本頁底部找到完整的 firebase.json 設定範例 (僅涵蓋 Firebase Hosting)。請注意，firebase.json 檔案也可能包含其他 Firebase 服務的設定。

您可以使用 Hosting REST API 查看已部署的 firebase.json 內容。

Hosting 回應的優先順序

本頁所述的不同 Firebase Hosting 設定選項有時會重疊。如果發生衝突，Hosting 會依下列優先順序決定回應方式：

1. 開頭為 /__/* 路徑區段的保留命名空間
2. 已設定的重新導向
3. 完全比對的靜態內容
4. 已設定的重寫
5. 自訂 404 網頁
6. 預設 404 頁面

如果您使用i18n 重寫，則會擴大完全比對和 404 處理優先順序的範圍，以便納入「i18n 內容」。

指定要部署的檔案

預設 firebase.json 檔案中包含的預設屬性 public 和 ignore，可定義專案目錄中應部署至 Firebase 專案的檔案。

firebase.json 檔案中的預設 hosting 設定如下所示：

"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 屬性會指定要忽略的部署檔案。它可以採用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 內容新增至檔案。

如果瀏覽器在網域或子網域中觸發 404 Not Found 錯誤，Firebase Hosting 就會顯示這個自訂 404.html 頁面的內容。

設定重新導向

選用
如果您已移動網頁，或想縮短網址，請使用網址重新導向功能來避免出現無效連結。舉例來說，您可以將瀏覽器從 example.com/team 重新導向至 example.com/about.html。

如要指定網址重新導向，請建立包含物件陣列 (稱為「重新導向規則」) 的 redirects 屬性。在每個規則中指定網址模式，如果與要求網址路徑相符，就會觸發 Hosting 回應，並將要求重新導向至指定的目標網址。

以下是 redirects 屬性的基本結構。這個範例會透過向 /bar 提出新要求，將要求重新導向至 /foo。

"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 值與所有網址路徑進行比較。如果找到相符項目，Firebase Hosting 原始伺服器就會傳送 HTTPS 重新導向回應，告知瀏覽器在 destination 網址上提出新要求。

擷取重新導向的網址區段

選用
有時您可能需要擷取重新導向規則網址模式的特定區段 (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
  } ]
}

設定重寫

選用
使用重寫功能，針對多個網址顯示相同內容。重寫功能在比對模式時特別實用，因為您可以接受任何符合模式的網址，並讓用戶端程式碼決定要顯示的內容。

您也可以使用重寫功能，支援使用 HTML5 pushState 進行導覽的應用程式。當瀏覽器嘗試開啟符合指定 source 或 regex 網址模式的網址路徑時，瀏覽器會改為取得 destination 網址的檔案內容。

如要指定網址重寫作業，請建立包含物件陣列 (稱為「重寫規則」) 的 rewrites 屬性。在每個規則中指定網址模式，如果與要求網址路徑相符，就會觸發 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 只會在網址路徑不符合指定 source 或 regex 網址模式時，才套用重寫規則。當要求觸發重寫規則時，瀏覽器會傳回指定 destination 檔案的實際內容，而非 HTTP 重新導向。

將要求直接傳送至函式

您可以使用 rewrites 從 Firebase Hosting 網址提供函式。以下範例節錄自使用 Cloud Functions 放送動態內容。

舉例來說，如要將 Hosting 網站上 /bigben 頁面的所有要求導向執行 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) 後，您就可以透過下列網址存取函式：

• 您的 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 從 Firebase Hosting 網址存取 Cloud Run 容器。以下範例節錄自使用 Cloud Run 提供動態內容。

舉例來說，如要將 Hosting 網站上 /helloworld 頁面的所有要求導向 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) 後，您可以透過下列網址存取容器映像檔：

• 您的 Firebase 子網域：
  PROJECT_ID.web.app/helloworld和 PROJECT_ID.firebaseapp.com/helloworld

• 任何已連結的自訂網域：
  CUSTOM_DOMAIN/helloworld

使用 Hosting 將要求重新導向至 Cloud Run 容器時，支援的 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
    } ]
  }

如要在 firebase.json 檔案中設定 Dynamic Links，請遵循下列步驟：

設定標頭

選用
標頭可讓用戶端和伺服器在傳送要求或回應時，一併傳遞其他資訊。部分標頭組合可能會影響瀏覽器處理網頁及其內容的方式，包括存取控制、驗證、快取和編碼。

如要指定自訂的檔案專屬回應標頭，請建立包含標頭物件陣列的 headers 屬性。在每個物件中指定網址模式，如果與要求網址路徑相符，就會觸發 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 屬性控制網址是否應包含 .html 擴充功能。

在 true 時，Hosting 會自動從上傳檔案網址中移除 .html 擴充功能。如果在要求中新增 .html 擴充功能，Hosting 會執行 301 重新導向至相同路徑，但會移除 .html 擴充功能。

以下說明如何透過加入 cleanUrls 屬性，控管網址中是否要加入 .html：

"hosting": {
  // ...

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

控制尾部斜線

選用
trailingSlash 屬性可讓您控制靜態內容網址是否應包含尾端斜線。

• 當 true 時，Hosting 會將網址重新導向，並加上尾部斜線。
• 當 false 時，Hosting 會重新導向網址，移除結尾斜線。
• 如果未指定，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 - 只比對 public 目錄根目錄中的 firebase.json 檔案

• **：比對任意子目錄中的任何檔案或資料夾

• *：只比對 public 目錄根目錄中的檔案和資料夾

• **/.*：比對任意子目錄中以 . 開頭的任何檔案 (通常是隱藏檔案，例如 .git 資料夾中的檔案)

• **/node_modules/**：比對 node_modules 資料夾任意子目錄中的任何檔案或資料夾，該資料夾本身可位於 public 目錄的任意子目錄中

• **/*.@(jpg|jpeg|gif|png) - 比對任意子目錄中的任何檔案，該檔案結尾必須與下列其中一個字串完全相符：.jpg、.jpeg、.gif 或 .png

完整 Hosting 設定範例

以下是 Firebase Hosting 的完整 firebase.json 設定範例。請注意，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",

  }
}