Catch up on highlights from Firebase at Google I/O 2023. Learn more

配置託管行為

借助 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文件中包含的默認屬性 - publicignore - 定義項目目錄中的哪些文件應部署到 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 模式的特定段( sourceregex值),然後在規則的destination路徑中重新使用這些段。

配置重寫

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

您還可以使用重寫來支持使用HTML5 PushState進行導航的應用程序。當瀏覽器嘗試打開與指定sourceregex 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屬性包含一組重寫規則,其中每個規則必須包含下表中的字段。

僅當與sourceregex 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/bigbenPROJECT_ID .firebaseapp.com/bigben

  • 任何連接的自定義域
    CUSTOM_DOMAIN /bigben

當使用 Hosting 將請求重定向到函數時,支持的 HTTP 請求方法包括GETPOSTHEADPUTDELETEPATCHOPTIONS 。不支持REPORTPROFIND等其他方法。

將請求直接發送到 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/helloworldPROJECT_ID .firebaseapp.com/helloworld

  • 任何連接的自定義域
    CUSTOM_DOMAIN /helloworld

使用 Hosting 將請求重定向到 Cloud Run 容器時,支持的 HTTP 請求方法包括GETPOSTHEADPUTDELETEPATCHOPTIONS 。不支持REPORTPROFIND等其他方法。

為了獲得最佳性能,請使用以下區域將您的 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.jsonapple-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作為sourceregex值。

(子) headers數組

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

每個子標頭必須包含一個keyvalue(請參閱接下來的兩行)。

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",

  }
}