配置託管行為

使用 Firebase 託管，您可以為網站請求配置自訂託管行為。

您可以為託管配置什麼？

  • 指定要部署到 Firebase 託管的本機專案目錄中的哪些檔案。學習如何。

  • 提供客製化的 404/Not Found 頁面。學習如何。

  • 為您已移動或刪除的頁面設定redirects 。學習如何。

  • 出於以下任何目的設定rewrites ：

  • 新增headers以傳遞有關請求或回應的附加訊息，例如瀏覽器應如何處理頁面及其內容（身份驗證、快取、編碼等）。學習如何。

  • 設定國際化 (i18n) 重寫以根據使用者的語言偏好和/或國家提供特定內容。了解如何操作（不同頁面）。

您在哪裡定義託管配置？

您可以在firebase.json檔案中定義 Firebase 託管配置。當您執行firebase init指令時，Firebase 會自動在專案目錄的根目錄下建立firebase.json檔案。

您可以在此頁面底部找到完整的firebase.json設定範例（僅涵蓋 Firebase 託管）。請注意， firebase.json檔案還可以包含其他 Firebase 服務的配置。

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

託管回應的優先順序

本頁所述的不同 Firebase 託管設定選項有時可能會重疊。如果存在衝突，Hosting 將使用以下優先順序確定其回應：

  1. 以/__/*路徑段開頭的保留命名空間
  2. 配置的重定向
  3. 精確匹配靜態內容
  4. 配置重寫
  5. 自訂 404頁面
  6. 預設 404 頁面

如果您使用i18n rewrites ，則精確匹配和 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屬性指定部署時要忽略的檔案。它可以像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/Not Found 頁面

選修的
當使用者嘗試存取不存在的頁面時，您可以提供自訂的404 Not Found錯誤。

在專案的public目錄中建立一個新文件，將其命名為404.html ，然後將自訂的404 Not Found內容新增至該文件。

如果瀏覽器在您的網域或子網域上觸發404 Not Found錯誤，Firebase Hosting 將顯示此自訂404.html頁面的內容。

配置重定向

選修的
如果您移動了頁面，請使用 URL 重新導向來防止連結損壞或縮短 URL。例如，您可以將瀏覽器從example.com/team重定向到example.com/about.html 。

透過建立包含物件數組（稱為「重定向規則」）的redirects屬性來指定 URL 重定向。在每個規則中，指定一個 URL 模式，如果該模式與請求 URL 路徑匹配，則觸發 Hosting 以重定向到指定的目標 URL 進行回應。

這是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 託管來源伺服器會傳送 HTTPS 重定向回應，告訴瀏覽器在destination URL 發出新請求。

場地描述
redirects
source （推薦）
或正規regex

URL 模式，如果與初始請求 URL 匹配，則觸發 Hosting 應用程式重定向

destination

瀏覽器應在其中發出新請求的靜態 URL

此 URL 可以是相對路徑或絕對路徑。

type

HTTPS 回應碼

  • 使用301類型表示“永久移動”
  • 使用302類型表示“找到”（暫時重定向）

捕獲重定向的 URL 段

選修的
有時，您可能需要擷取重定向規則的 URL 模式的特定段（ source或regex值），然後在規則的destination路徑中重新使用這些段。

配置重寫

選修的
使用重寫來顯示多個 URL 的相同內容。重寫對於模式匹配特別有用，因為您可以接受與模式匹配的任何 URL，並讓客戶端程式碼決定顯示什麼。

您也可以使用重寫來支援使用HTML5 PushState進行導覽的應用程式。當瀏覽器嘗試開啟與指定source或regex URL 模式相符的 URL 路徑時，瀏覽器將獲得destination URL 處的檔案內容。

透過建立包含物件數組的rewrites屬性（稱為「重寫規則」）來指定 URL 重寫。在每個規則中，指定一個 URL 模式，如果該模式與請求 URL 路徑匹配，則觸發 Hosting 進行回應，就像為服務提供了指定的目標 URL 一樣。

這是rewrites屬性的基本結構。此範例為index.html提供不存在的檔案或目錄的請求。

"hosting": {
  // ...

  // Serves index.html for requests to files or directories that do not exist
  "rewrites": [ {
    "source": "**",
    "destination": "/index.html"
  } ]
}

rewrites屬性包含一組重寫規則，其中每個規則必須包含下表中的欄位。

只有當與source或正規regex URL 模式相符的 URL 路徑中不存在檔案或目錄時，Firebase 託管才會套用重寫規則。當請求觸發重寫規則時，瀏覽器會傳回指定destination檔案的實際內容，而不是 HTTP 重新導向。

場地描述
rewrites
source （推薦）
或正規regex

URL 模式，如果與初始請求 URL 匹配，則觸發 Hosting 應用程式重寫

destination

必須存在的本地文件

此 URL 可以是相對路徑或絕對路徑。

直接請求函數

您可以使用rewrites來從 Firebase 託管 URL 提供函數。以下範例是使用 Cloud Functions 提供動態內容的摘錄。

例如，要引導來自託管網站上的頁面/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 ）後，可以透過以下 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從 Firebase 託管 URL 存取 Cloud Run 容器。以下範例是使用 Cloud Run 提供動態內容的摘錄。

例如，引導來自託管網站上的頁面/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 ）後，可以透過以下 URL 存取您的容器映像：

  • 您的 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 服務與託管並置：

  • us-west1
  • us-central1
  • us-east1
  • europe-west1
  • asia-east1

以下區域支援從託管重寫到 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

您可以使用rewrites來建立自訂網域動態連結。有關為動態連結設定自訂網域的詳細信息，請訪問動態連結文件。

  • 僅將您的自訂網域用於動態鏈接

    "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
  } ]
}

  • 指定用於動態連結的自訂網域路徑前綴

    "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檔案中配置動態連結需要以下內容：

場地描述
appAssociation

必須設定為AUTO

  • 如果您的配置中未包含此屬性，則appAssociation的預設值為AUTO 。
  • 透過將此屬性設為AUTO ，Hosting 可以在請求時動態產生assetlinks.json和apple-app-site-association檔。
rewrites
source

您要用於動態連結的路徑

與重寫 URL 路徑的規則不同，動態連結的重寫規則不能包含正規表示式。

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

URL 模式，如果與初始請求 URL 匹配，則觸發 Hosting 應用程式自訂標頭

若要建立與自訂 404 頁面相符的標頭，請使用404.html作為source或regex值。

（子） headers數組

託管應用於請求路徑的自訂標頭

每個子標頭必須包含一個key和value對（請參閱接下來的兩行）。

key標頭的名稱，例如Cache-Control
value標頭的值，例如max-age=7200

您可以在描述提供動態內容和託管微服務的託管部分中了解有關Cache-Control的更多資訊。您還可以了解有關CORS標頭的更多資訊。

控制.html副檔名

選修的
cleanUrls屬性可讓您控制 URL 是否應包含.html副檔名。

當true時，託管會自動從上傳的檔案 URL 中刪除.html副檔名。如果請求中新增了.html副檔名，託管會執行301重定向到相同路徑，但會消除.html副檔名。

以下是如何透過包含cleanUrls屬性來控制 URL 中包含.html的情況：

"hosting": {
  // ...

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

控制尾部斜杠

選修的
trailingSlash屬性可讓您控制靜態內容 URL 是否應包含尾部斜線。

  • 當true時，託管會重定向 URL 以新增尾部斜線。
  • 當false時，託管會重新導向 URL 以刪除尾部斜線。
  • 如果未指定，Hosting 僅對目錄索引檔案使用尾部斜線（例如about/index.html ）。

以下是如何透過添加trailingSlash屬性來控制尾部斜線：

"hosting": {
  // ...

  // Removes trailing slashes from URLs
  "trailingSlash": false
}

trailingSlash屬性不會影響 Cloud Functions 或 Cloud Run 提供的動態內容的重寫。

全域模式匹配

Firebase 託管組態選項廣泛使用具有 extglob的 glob 模式比對表示法，類似於 Git 處理gitignore規則和Bower處理ignore規則的方式。此 wiki 頁面是更詳細的參考，但以下是對此頁面上使用的範例的解釋：

  • firebase.json — 只匹配public目錄根目錄下的firebase.json文件

  • ** — 符合任意子目錄中的任何檔案或資料夾

  • * — 只符合public目錄根目錄下的檔案和資料夾

  • **/.* — 匹配任何以. （通常是隱藏文件，如.git資料夾中）在任意子目錄中

  • **/node_modules/** — 符合node_modules資料夾的任意子目錄中的任何檔案或資料夾，該資料夾本身可以位於public目錄的任意子目錄中

  • **/*.@(jpg|jpeg|gif|png) — 符合任何子目錄中以下列之一結尾的任何檔案： .jpg 、 .jpeg 、 .gif或.png

完整託管設定範例

以下是 Firebase 託管的完整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",

  }
}