了解 2023 年 Google I/O 大会上介绍的 Firebase 亮点。了解详情

配置託管行為

借助 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 託管的目錄。默認值為名為public的目錄，但您可以指定任何目錄的路徑，只要它存在於您的項目目錄中即可。

以下是要部署的目錄的默認指定名稱：

"hosting": {
  "public": "public"

  // ...
}

您可以將默認值更改為要部署的目錄：

"hosting": {
  "public": "dist/app"

  // ...
}

忽略

選修的
ignore屬性指定在部署時要忽略的文件。它可以採用與Git處理.gitignore相同的方式處理glob 。

以下是要忽略的文件的默認值：

"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 託管將顯示此自定義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 託管在每個請求開始時將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屬性包含一組重寫規則，其中每個規則必須包含下表中的字段。

如果 URL 路徑中不存在與指定source或正則regex 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": "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

使用託管將請求重定向到 Cloud Run 容器時，支持的 HTTP 請求方法有GET 、 POST 、 HEAD 、 PUT 、 DELETE 、 PATCH和OPTIONS 。不支持REPORT或PROFIND等其他方法。

目前，您可以在以下區域使用 Cloud Run 重寫和託管：

  • asia-east1
  • asia-east2
  • asia-northeast1
  • asia-northeast2
  • asia-northeast3
  • asia-south1
  • asia-southeast1
  • asia-southeast2
  • australia-southeast1
  • europe-north1
  • europe-west1
  • europe-west2
  • europe-west3
  • europe-west4
  • europe-west6
  • northamerica-northeast1
  • southamerica-east1
  • us-central1
  • us-east1
  • us-east4
  • us-west1

您可以使用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 ，託管可以在請求時動態生成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數組

Hosting 應用於請求路徑的自定義標頭

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

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

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

控制.html擴展名

選修的
cleanUrls屬性允許您控制 URL 是否應包含.html擴展名。

當為true時，Hosting 會自動從上傳的文件 URL 中刪除.html擴展名。如果在請求中添加了.html擴展名，Hosting 會執行301重定向到同一路徑，但會刪除.html擴展名。

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

"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 託管配置選項廣泛使用 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",

  }
}