配置託管行為

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

您可以為託管配置什麼？

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

• 提供定制的 404/Not Found 頁面。學習如何。

• 為您移動或刪除的頁面設置redirects 。學習如何。

• 為任何這些目的rewrites ：

  • 為多個 URL 顯示相同的內容。學習如何。

  • 從託管 URL 提供功能或訪問 Cloud Run 容器。學習方法：函數或容器。

  • 創建自定義域動態鏈接。學習如何。

• 添加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文件中包含的默認屬性（ 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屬性指定在部署時要忽略的文件。它可以採用與Git處理.gitignore相同的方式處理glob 。

以下是要忽略的文件的默認值：

"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 託管將顯示此自定義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
  } ]
}

"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 託管在每個請求開始時將source或regex值與所有 URL 路徑進行比較（在瀏覽器確定文件或文件夾是否存在於該路徑之前）。如果找到匹配項，則 Firebase 託管源服務器會發送 HTTPS 重定向響應，告知瀏覽器在destination URL 發出新請求。

捕獲用於重定向的 URL 段

選修的
有時，您可能需要捕獲重定向規則的 URL 模式的特定部分（ source或regex值），然後在規則的destination路徑中重新使用這些部分。

"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
  } ]
}

"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 路徑匹配，則觸發 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屬性包含一組重寫規則，其中每個規則必須包含下表中的字段。

如果 URL 路徑中不存在與指定source或正則regex URL 模式匹配的文件或目錄，則 Firebase 託管僅應用重寫規則。當請求觸發重寫規則時，瀏覽器返回指定destination文件的實際內容，而不是 HTTP 重定向。

直接請求函數

您可以使用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/bigben和PROJECT_ID .firebaseapp.com/bigben

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

當使用 Hosting 將請求重定向到函數時，支持的 HTTP 請求方法是GET 、 POST 、 HEAD 、 PUT 、 DELETE 、 PATCH和OPTIONS 。不支持REPORT或PROFIND等其他方法。

將請求直接發送到 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

使用託管將請求重定向到 Cloud Run 容器時，支持的 HTTP 請求方法有GET 、 POST 、 HEAD 、 PUT 、 DELETE 、 PATCH和OPTIONS 。不支持REPORT或PROFIND等其他方法。

目前，您可以在以下區域使用 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文件中配置動態鏈接需要以下內容：

配置標頭

選修的
標頭允許客戶端和服務器傳遞附加信息以及請求或響應。某些標頭集會影響瀏覽器處理頁面及其內容的方式，包括訪問控制、身份驗證、緩存和編碼。

通過創建包含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屬性包含一組定義，其中每個定義必須包含下表中的字段。

您可以在描述提供動態內容和託管微服務的託管部分中了解有關Cache-Control的更多信息。您還可以了解有關CORS標頭的更多信息。

控制.html擴展名

選修的
cleanUrls屬性允許您控制 URL 是否應包含.html擴展名。

當為true時，Hosting 會自動從上傳的文件 URL 中刪除.html擴展名。如果在請求中添加了.html擴展名，Hosting 會執行301重定向到同一路徑，但會刪除.html擴展名。

以下是如何通過包含cleanUrls屬性來控制.html在 URL 中的包含：

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

  }
}