透過 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 託管設定選項有時可能會重疊。若有衝突,託管會以下列優先順序決定回應:
如果您使用 i18n 重寫功能,完全比對和 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
屬性可指定部署時要忽略的檔案。使用的 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
內容新增至檔案。
如果瀏覽器在您的網域或子網域上觸發 404 Not Found
錯誤,Firebase 代管會顯示這個自訂 404.html
頁面的內容。
設定重新導向
選用
如果您移動網頁或縮短網址,請使用網址重新導向來避免無效連結。舉例來說,您可以將瀏覽器從 example.com/team
重新導向至 example.com/about.html
。
建立包含物件陣列 (稱為「重新導向規則」) 的 redirects
屬性,即可指定網址重新導向。請在每項規則中指定網址模式,如果與要求網址路徑相符,就會觸發託管,以重新導向至指定到達網頁網址的回應。
以下是 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 託管會將 source
或 regex
值與每個要求開頭的所有網址路徑進行比較 (瀏覽器會先判斷該路徑是否存在檔案或資料夾)。如果找到相符項目,Firebase 代管來源伺服器會傳送 HTTPS 重新導向回應,讓瀏覽器透過 destination
網址發出新要求。
欄位 | 說明 | |
---|---|---|
redirects |
||
source (建議) 或 regex
|
網址模式,如果與初始要求網址相符,就會觸發「託管」來套用重新導向 |
|
destination |
瀏覽器應發出新要求的靜態網址 這個網址可以是相對或絕對路徑。 |
|
type |
HTTPS 回應代碼
|
擷取重新導向的網址區段
選用
有時您可能需要擷取重新導向規則網址模式的特定部分 (source
或 regex
值),然後在規則的 destination
路徑中重複使用這些區隔。
設定重寫
選用
使用重寫功能讓多個網址顯示相同的內容。重新撰寫特別適用於模式比對,因為您可以接受任何符合模式的網址,並讓用戶端程式碼決定要顯示哪些內容。
您也可以使用重寫功能,支援使用 HTML5PushState 進行瀏覽的應用程式。如果瀏覽器嘗試開啟符合指定 source
或 regex
網址模式的網址路徑,則瀏覽器會改將檔案內容提供給 destination
網址。
建立含有物件陣列 (稱為「重寫規則」) 的 rewrites
屬性,即可指定網址重寫。在每項規則中指定網址模式,如果與要求網址路徑相符,則觸發託管會假設服務已提供指定的目的地網址來回應。
以下是 rewrites
屬性的基本結構。此範例針對不存在的檔案或目錄的要求提供 index.html
。
"hosting": {
// ...
// Serves index.html for requests to files or directories that do not exist
"rewrites": [ {
"source": "**",
"destination": "/index.html"
} ]
}
rewrites
屬性包含重寫規則的陣列,其中每項規則都必須包含下表中的欄位。
Firebase 託管只會在檔案或目錄不存在的網址路徑符合指定 source
或 regex
網址模式時,才會套用重寫規則。當要求觸發重寫規則時,瀏覽器會傳回指定 destination
檔案的實際內容,而不是 HTTP 重新導向。
欄位 | 說明 | |
---|---|---|
rewrites |
||
source (建議) 或 regex
|
網址模式,如果與初始要求網址相符,就會觸發託管來套用重寫作業 |
|
destination |
必須確實存在的本機檔案 這個網址可以是相對或絕對路徑。 |
將要求直接導向函式
您可以使用 rewrites
從 Firebase 託管網址提供函式。以下範例是使用 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
) 後,即可透過下列網址存取函式:
您的 Firebase 子網域:
PROJECT_ID.web.app/bigben
和PROJECT_ID.firebaseapp.com/bigben
任何已連結的自訂網域:
CUSTOM_DOMAIN/bigben
透過託管將要求重新導向至函式時,支援的 HTTP 要求方法為 GET
、POST
、HEAD
、PUT
、DELETE
、PATCH
和 OPTIONS
。不支援 REPORT
或 PROFIND
等其他方法。
將要求直接導向 Cloud Run 容器
您可以使用 rewrites
,從 Firebase 託管網址存取 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
) 後,您可以透過下列網址存取容器映像檔:
您的 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 服務與「託管」存放在相同位置:
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
建立自訂網域 Dynamic Links
您可以使用 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 |
必須設為
|
|
rewrites |
||
source |
要用於 Dynamic Links 的路徑 有別於重新寫入網址路徑的規則,動態連結重寫規則不得包含規則運算式。 |
|
dynamicLinks |
必須設為 true
|
設定標頭
選用
標頭可讓用戶端和伺服器連同要求或回應一併傳遞其他資訊。部分標頭可能會影響瀏覽器處理網頁及其內容的方式,包括存取權控管、驗證、快取和編碼。
建立包含標頭物件陣列的 headers
屬性,指定檔案專屬的自訂回應標頭。在每個物件中指定網址模式,如果與要求網址路徑相符,就會觸發託管來套用指定的自訂回應標頭。
以下是 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
|
網址模式,如果與初始要求網址相符,就會觸發「託管」來套用自訂標頭 如要建立用來比對自訂 404 網頁的標頭,請使用 |
||
(子-)headers 陣列 |
「託管」套用至要求路徑的自訂標頭 每個子標題都必須包含 |
||
key |
標頭名稱,例如 Cache-Control |
||
value |
標頭的值,例如 max-age=7200 |
如要進一步瞭解 Cache-Control
,請參閱有關提供動態內容與託管微服務的「託管」一節。也可以進一步瞭解 CORS 標頭。
控制 .html
擴充功能
選用
cleanUrls
屬性可讓您控制網址是否應包含 .html
副檔名。
如果為 true
,「託管」會自動從上傳的檔案網址捨棄 .html
擴充功能。如果在要求中加入 .html
擴充功能,託管會執行 301
重新導向到相同路徑,但會刪除 .html
副檔名。
以下說明如何加入 cleanUrls
屬性,以控制網址是否包含 .html
:
"hosting": {
// ...
// Drops `.html` from uploaded URLs
"cleanUrls": true
}
控制結尾斜線
選用
trailingSlash
屬性可讓您控制是否在靜態內容網址結尾加上斜線。
- 如果設為
true
,代管重新導向的網址會在結尾加上斜線。 - 如果設為
false
,主機會重新導向至網址以移除結尾的斜線。 - 如未指定,「託管」只會使用目錄索引檔案結尾的斜線 (例如
about/index.html
)。
以下說明如何新增 trailingSlash
屬性來控制結尾的斜線:
"hosting": {
// ...
// Removes trailing slashes from URLs
"trailingSlash": false
}
trailingSlash
屬性不會影響 Cloud Functions 或 Cloud Run 提供的動態內容重寫。
Glob 模式比對
Firebase 託管設定選項大量使用 extglob 的 glob 模式比對標記法,與 Git 處理 gitignore
規則和 Bower 處理 ignore
規則的方式類似。這個維基網頁比較更詳細的參考資訊,但以下為本頁面的範例:
firebase.json
:僅比對public
目錄根目錄中的firebase.json
檔案**
:比對任意子目錄中的任何檔案或資料夾*
- 只比對public
目錄根目錄中的檔案和資料夾**/.*
:比對任意子目錄中,比對開頭為.
的任何檔案 (通常是隱藏檔案,例如.git
資料夾中)**/node_modules/**
:比對node_modules
資料夾任意子目錄中的任何檔案或資料夾,該子目錄可以位於public
目錄的任意子目錄中**/*.@(jpg|jpeg|gif|png)
- 比對任意子目錄中,結尾為下列其中一個檔案的任何檔案:.jpg
、.jpeg
、.gif
或.png
Full Hosting 設定範例
以下是 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",
}
}