配置託管行為

借助 Firebase 託管,您可以為對您網站的請求配置自定義託管行為。

您可以為託管配置什麼?

  • 指定要部署到 Firebase 託管的本地項目目錄中的哪些文件。學習怎樣。

  • 提供定制的 404/未找到頁面。學習怎樣。

  • 為您已移動或刪除的頁面設置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 託管的目錄。默認值為名為public的目錄,但您可以指定任何目錄的路徑,只要它存在於您的項目目錄中。

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

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

  // ...
}

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

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

  // ...
}

忽視

可選的
ignore屬性指定部署時要忽略的文件。它可以像Git處理.gitignore一樣使用.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 託管將顯示此自定義404.html頁面的內容。

配置重定向

可選的
如果您移動頁面或縮短 URL,請使用 URL 重定向來防止鏈接斷開。例如,您可以將瀏覽器從example.com/team重定向到example.com/about.html

通過創建包含對像數組(稱為“重定向規則”)的redirects屬性來指定 URL 重定向。在每個規則中,指定一個 URL 模式,如果與請求 URL 路徑匹配,則會觸發 Hosting 以重定向到指定目標 URL 進行響應。

這是redirects屬性的基本結構。此示例通過向/bar發出新請求將請求重定向到/foo

"hosting": {
  // ...

  // Returns a permanent redirect to "/bar" for requests to "/foo" (but not "/foo/**")
  "redirects": [ {
    "source": "/foo",
    "destination": "/bar",
    "type": 301
  } ]
}

redirects屬性包含一個重定向規則數組,其中每個規則必須包含下表中的字段。

Firebase 託管在每個請求開始時(在瀏覽器確定該路徑中是否存在文件或文件夾之前)將sourceregex值與所有 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屬性包含一個重寫規則數組,其中每個規則必須包含下表中的字段。

Firebase 託管僅在與指定sourceregex URL 模式匹配的 URL 路徑中不存在文件或目錄時應用重寫規則。當請求觸發重寫規則時,瀏覽器會返回指定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)
  } ]
}

添加此重寫規則並部署到 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 重寫與託管一起使用:

  • 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 ,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數組

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屬性來控制在 URL 中包含.html的方法:

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

  }
}