設定託管行為

使用 Firebase Hosting,即可針對以下項目設定自訂託管行為: 向您的網站提出要求

您可以為 Hosting 進行哪些設定?

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

  • 顯示自訂的「404/找不到」網頁。瞭解詳情

  • 為已移動或刪除的頁面設定 redirects瞭解做法。

  • 為下列任一用途設定 rewrites

    • 使用多個網址顯示相同內容。瞭解做法。

    • 透過 Hosting 網址提供函式或存取 Cloud Run 容器。瞭解運作方式:函式或 「容器」

    • 建立自訂網域 Dynamic Link瞭解做法。

  • 新增 headers 以傳送與要求或 回應,例如瀏覽器應如何處理網頁及其內容 (驗證、快取、編碼等)。瞭解詳情

  • 設定國際化 (i18n) 改寫功能,提供特定內容 使用者的語言偏好設定和/或國家/地區 瞭解詳情 (其他頁面)。

您在哪裡定義 Hosting 設定?

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

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

您可以使用firebase.json Hosting REST API

Hosting 回應的優先順序

本頁說明的各種 Firebase Hosting 設定選項 有時會重疊如有任何衝突,Hosting 會判斷其 回應:

  1. 開頭為 /__/* 路徑區段的保留命名空間
  2. 已設定的重新導向
  3. 完全相符的靜態內容
  4. 已設定的重寫
  5. 自訂 404 頁面
  6. 預設 404 網頁
,瞭解如何調查及移除這項存取權。

如果您使用 i18n 重寫,完全相符 ,處理優先順序 404 會擴大處理範圍,以因應您的「i18n」 內容。

指定要部署的檔案

包含預設屬性 (publicignore) 預設 firebase.json 檔案中定義了專案目錄中的檔案 都應部署至 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 內容新增至檔案。

如果符合以下條件,Firebase Hosting 就會顯示這個自訂 404.html 網頁的內容 瀏覽器在您的網域或子網域上觸發 404 Not Found 錯誤。

設定重新導向

選用
移動網頁後,使用網址重新導向來避免連結中斷 或縮短網址舉例來說,您可以將瀏覽器 example.com/teamexample.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
  } ]
}

redirects 屬性包含重新導向規則陣列,其中每個規則都在其中 必須包含下表的欄位。

Firebase Hosting 會將 sourceregex 值與所有網址進行比較 起始路徑時 (瀏覽器會先判定 該路徑就存在於該路徑之外如果找到相符項目,則 Firebase Hosting 來源伺服器傳送 HTTPS 重新導向回應,指出 再前往 destination 網址發出新要求。

欄位 說明
redirects
source (建議)
regex

網址模式,如果與初始要求網址相符,就會觸發 Hosting 來套用重新導向

destination

瀏覽器應發出新要求的靜態網址

這個網址可以是相對或絕對路徑。

type

HTTPS 回應代碼

  • 針對「永久移動」使用 301 類型
  • 針對「找到」使用302類型(暫時重新導向)

擷取重新導向的網址區段

選用
有時候,您可能必須擷取重新導向規則網址的特定區段 模式 (sourceregex 值),然後在 規則的 destination 路徑。

設定重寫

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

你也可以使用重新編寫功能,支援使用 HTML5 PushState 以便瀏覽。當瀏覽器嘗試開啟符合 指定的 sourceregex 網址模式時,瀏覽器就會收到 位於 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"
  } ]
}

rewrites 屬性包含重寫規則的陣列,其中每項規則 必須包含下表的欄位。

Firebase Hosting」只會在檔案或目錄未套用重寫規則的情況下套用 存在於與指定 sourceregex 網址模式相符的網址路徑。 當要求觸發重新寫入規則時,瀏覽器會傳回實際內容 的 destination 檔案,而不是 HTTP 重新導向。

欄位 說明
rewrites
source (建議)
regex

網址模式,如果與初始要求網址相符,就會觸發 Hosting 套用重寫

destination

必須確實存在的本機檔案

這個網址可以是相對或絕對路徑。

將要求直接導向函式

您可以使用 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 要求) 方法為 GETPOSTHEADPUTDELETEPATCHOPTIONS。 但不支援 REPORTPROFIND 等其他方法。

將要求直接傳送至 Cloud Run 容器

您可以使用 rewrites,從Cloud Run Firebase Hosting網址。以下範例是取自 使用 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 要求方法為 GETPOSTHEADPUTDELETEPATCHOPTIONSREPORTPROFIND 等其他方法則不受支援。

為獲得最佳效能,請在下列區域為您的 Cloud Run 服務與 Hosting 並用:

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

您可以在Cloud RunHosting 下列區域:

  • 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 建立自訂網域 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,請遵循下列步驟:

欄位 說明
appAssociation

必須設為 AUTO

  • 如果未在設定中加入這個屬性, appAssociation 的預設值為 AUTO
  • 將此屬性設為 AUTO 後,Hosting 就能 動態產生 assetlinks.json 偵測到 apple-app-site-association 個檔案 需要的 SDK
rewrites
source

您希望 Dynamic Links 使用的路徑

有別於重新寫入網址路徑的規則,為 Dynamic Links 改寫規則 不得包含規則運算式。

dynamicLinks 必須設為 true

設定標頭

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

建立 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": "*"
    } ]
  } ]
}

headers 屬性包含定義的陣列,其中每項定義 必須包含下表的欄位。

欄位 說明
headers
source (建議)
regex

網址模式,如果與初始要求網址相符,就會觸發 Hosting 即可套用自訂標頭

如何建立要用來比對 自訂 404 網頁,請使用 404.html 做為 sourceregex 的值。

(子-)headers 陣列

Hosting 套用至要求路徑的自訂標頭

每個子標題都必須包含 keyvalue 配對 (請參閱接下來兩列)。

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

如要進一步瞭解 Cache-Control,請前往 Hosting 部分,說明如何提供動態內容與代管功能 微服務型架構你也可以進一步瞭解 CORS 標頭。

控制 .html 擴充功能

選用
cleanUrls 屬性可讓您控制是否網址 應包含 .html 副檔名。

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

以下說明如何加入 .htmlcleanUrls 屬性:

"hosting": {
  // ...

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

控制結尾斜線

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

  • 如果設為 trueHosting 會重新導向網址以在結尾加上斜線。
  • 如果設為 falseHosting 會重新導向網址以移除結尾的斜線。
  • 如果未指定,Hosting 只會在目錄索引檔案 (例如 about/index.html) 中使用尾部斜線。

以下說明如何新增 trailingSlash 屬性來控制結尾的斜線:

"hosting": {
  // ...

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

trailingSlash 屬性不會影響動態內容的重寫作業 由 Cloud FunctionsCloud Run 提供。

Glob 模式比對

Firebase Hosting 設定選項會大量使用glob 模式比對符號與 extglob,類似於 Git 處理 gitignore 規則,以及 Bower 處理 ignore 規則的方式。這個維基網頁是更詳細的參考資訊 以下為這個網頁使用的範例:

  • firebase.json - 只比對根目錄中的 firebase.json 檔案 public 目錄的

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

  • * - 只比對根層級的檔案和資料夾 public 目錄

  • **/.*:比對任何開頭為 . 的檔案 (通常為隱藏檔案, 例如 .git 資料夾中)

  • **/node_modules/**:比對任意檔案或資料夾中的任何檔案或資料夾 node_modules 資料夾的子目錄,可以位於任意資料夾中 public 目錄的子目錄

  • **/*.@(jpg|jpeg|gif|png):比對任意檔案中的任何檔案 結尾為下列其中一個項目的子目錄:.jpg.jpeg.gif.png

完整的 Hosting 設定範例

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

  }
}