借助Firebase託管,您可以配置對網站請求的自定義託管行為。
您可以為主機配置什麼?
在本地項目目錄中指定要部署到Firebase Hosting的文件。學習怎樣。
服務自定義的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配置選項有時可能會重疊。如果存在衝突,託管將使用以下優先級順序確定其響應:
如果您使用的是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 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 /未找到頁面
可選的
當用戶嘗試訪問不存在的頁面時,可以提供一個自定義的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
} ]
}
"hosting": {
// ...
// Add the "redirects" attribute within "hosting"
"redirects": [ {
// Returns a permanent redirect to "/bar" for requests to "/foo" (but not "/foo/**")
"source": "/foo",
"destination": "/bar",
"type": 301
}, {
// Returns a permanent redirect to "/bar" for requests to both "/foo" and "/foo/**"
"source": "/foo{,/**}"
"destination": "/bar"
"type": 301
}, {
// Returns a temporary redirect for all requests to files or directories in the "firebase" directory
"source": "/firebase/**",
"destination": "https://firebase.google.com/",
"type": 302
}, {
// A regular expression-based redirect equivalent to the above behavior
"regex": "/firebase/.*",
"destination": "https://firebase.google.com/",
"type": 302
} ]
}
redirects
屬性包含一個重定向規則數組,其中每個規則必須包含下表中的字段。
Firebase Hosting在每個請求開始時(在瀏覽器確定該路徑上是否存在文件或文件夾之前)將source
或regex
值與所有URL路徑進行比較。如果找到匹配項,則Firebase託管源服務器將發送HTTPS重定向響應,告訴瀏覽器在destination
URL處發出新請求。
場地 | 描述 | |
---|---|---|
redirects | ||
source (推薦)或 regex | URL模式,如果與初始請求URL匹配,則會觸發Hosting應用重定向 | |
destination | 瀏覽器應在其中發出新請求的靜態URL 該URL可以是相對路徑,也可以是絕對路徑。 | |
type | HTTPS響應代碼
|
捕獲URL段以進行重定向
可選的
有時,您可能需要捕獲重定向規則的URL模式的特定段( source
或regex
值),然後在規則的destination
路徑中重新使用這些段。
如果您使用的是source
字段(即,為URL模式指定glob),則可以通過包含:
前綴來標識段來捕獲段。如果您還需要捕獲該段之後的其餘URL路徑,請在該段之後立即添加一個*
。例如:
"hosting": { // ... "redirects": [ { "source": "/blog/:post*", // captures the entire URL segment beginning at "post" "destination": "https://blog.myapp.com/:post", // includes the entire URL segment identified and captured by the "source" value "type": 301 }, { "source": "/users/:id/profile", // captures only the URL segment "id", but nothing following "destination": "/users/:id/newProfile", // includes the URL segment identified and captured by the "source" value "type": 301 } ] }
如果使用regex
字段(即,為URL模式指定RE2正則表達式),則可以使用命名或未命名的RE2捕獲組捕獲段。命名的捕獲組可以在destination
字段中使用:
前綴,而未命名的捕獲組可以通過它們在regex
值中的數字索引(從1開始索引)來引用。例如:
"hosting": { // ... "redirects": [ { "regex": "/blog/(?P<post>.+)", // if you're familiar with PCRE, be aware that RE2 requires named capture groups to begin with ?P "destination": "https://blog.myapp.com/:post", // includes the entire URL segment identified and captured by the `regex` value "type": 301 }, { "regex": "/users/(\d+)/profile", // uses the \d directive to only match numerical path segments "destination": "/users/:1/newProfile", // the first capture group to be seen in the `regex` value is named 1, and so on "type": 301 } ] }
配置重寫
可選的
使用重寫為多個URL顯示相同的內容。重寫對於模式匹配特別有用,因為您可以接受任何與模式匹配的URL,並讓客戶端代碼決定要顯示的內容。
您還可以使用重寫來支持使用HTML5 pushState進行導航的應用程序。當瀏覽器嘗試打開與指定的source
或regex
URL模式匹配的URL路徑時,將在destination
URL處為瀏覽器提供文件內容。
通過創建包含對像數組的rewrites
屬性(稱為“重寫規則”)來指定URL重寫。在每個規則中,指定一個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"
} ]
}
"hosting": { // ... // Add the "rewrites" attribute within "hosting" "rewrites": [ { // Serves index.html for requests to files or directories that do not exist "source": "**", "destination": "/index.html" }, { // Serves index.html for requests to both "/foo" and "/foo/**" // Using "/foo/**" only matches paths like "/foo/xyz", but not "/foo" "source": "/foo{,/**}", "destination": "/index.html" }, { // A regular expression-based rewrite equivalent to the above behavior "regex": "/foo(/.*)?", "destination": "/index.html" }, { // Excludes specified pathways from rewrites "source": "!/@(js|css)/**", "destination": "/index.html" } ] }
rewrites
屬性包含一個重寫規則數組,其中每個規則必須包括下表中的字段。
僅當與指定source
或regex
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": "bigben"
} ]
}
添加此重寫規則並部署到Firebase(使用firebase deploy
)後,可以通過以下URL來訪問您的函數:
您的Firebase子域:
PROJECT_ID .web.app/bigben
和PROJECT_ID .firebaseapp.com/bigben
任何連接的自定義域:
CUSTOM_DOMAIN /bigben
將請求直接發送到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
創建自定義域動態鏈接
您可以使用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 | 必須設置為
| |
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": "*"
} ]
} ]
}
"hosting": { // ... // Add the "headers" attribute within "hosting" "headers": [ { // Applies a CORS header for all font files "source": "**/*.@(eot|otf|ttf|ttc|woff|font.css)", "headers": [ { "key": "Access-Control-Allow-Origin", "value": "*" } ] }, { // Overrides the default 1 hour browser cache with a 2 hour cache for all image files "source": "**/*.@(jpg|jpeg|gif|png)", "headers": [ { "key": "Cache-Control", "value": "max-age=7200" } ] }, { // A regular expression-based rewrite equivalent to the above behavior "regex": ".+/\w+\.(jpg|jpeg|gif|png)$", "headers": [ { "key": "Cache-Control", "value": "max-age=7200" } ] }, { // Sets the cache header for 404 pages to cache for 5 minutes "source": "404.html", "headers": [ { "key": "Cache-Control", "value": "max-age=300" } ] } ] }
headers
屬性包含一個定義數組,其中每個定義必須包括下表中的字段。
場地 | 描述 | ||
---|---|---|---|
headers | |||
source (推薦)或 regex | 一個URL模式,如果與初始請求URL匹配,則會觸發Hosting應用自定義標頭 要創建與您的自定義404頁面匹配的標頭,請使用 | ||
(sub-) headers 數組 | 託管應用於請求路徑的自定義標頭 每個子標題都必須包含一個 | ||
key | 標頭名稱,例如Cache-Control | ||
value | 標頭的值,例如max-age=7200 |
您可以在“託管”部分中了解有關Cache-Control
更多信息,該部分描述瞭如何提供動態內容和託管微服務。您還可以了解有關CORS標頭的更多信息。
控制.html
擴展名
可選的cleanUrls
屬性使您可以控制URL是否應包含.html
擴展名。
如果為true
,則Hosting會自動從上傳的文件URL中刪除.html
擴展名。如果在請求中添加了.html
擴展名,託管將執行301
重定向到同一路徑,但會消除.html
擴展名。
以下是通過包含cleanUrls
屬性來控制URL中包含.html
的cleanUrls
:
"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",
}
}