Skonfiguruj zachowanie hostingu

Dzięki Hostingowi Firebase możesz skonfigurować niestandardowe zachowanie hostingu dla żądań do Twojej witryny.

Co możesz skonfigurować dla Hostingu?

  • Określ, które pliki w lokalnym katalogu projektu chcesz wdrożyć w Hostingu Firebase. Naucz się jak.

  • Podaj dostosowaną stronę 404/Nie znaleziono. Naucz się jak.

  • Skonfiguruj redirects dla stron, które zostały przeniesione lub usunięte. Naucz się jak.

  • Skonfiguruj rewrites w dowolnym z tych celów:

    • Pokaż tę samą treść dla wielu adresów URL. Naucz się jak.

    • Udostępniaj funkcję lub uzyskuj dostęp do kontenera Cloud Run z adresu URL hostingu. Dowiedz się, jak: funkcja lub kontener .

    • Utwórz niestandardową domenę Dynamic Link. Naucz się jak.

  • Dodaj headers , aby przekazać dodatkowe informacje o żądaniu lub odpowiedzi, takie jak sposób obsługi strony i jej zawartości przez przeglądarki (uwierzytelnianie, buforowanie, kodowanie itp.). Naucz się jak.

  • Skonfiguruj przepisywanie internacjonalizacji (i18n), aby wyświetlać określone treści w oparciu o preferencje językowe i/lub kraj użytkownika. Dowiedz się jak (inna strona).

Gdzie definiujesz konfigurację hostingu?

Konfigurację Hostingu Firebase definiujesz w pliku firebase.json . Firebase automatycznie tworzy plik firebase.json w katalogu głównym katalogu projektu po uruchomieniu polecenia firebase init .

Pełny przykład konfiguracji firebase.json (obejmujący tylko Hosting Firebase) znajdziesz na dole tej strony. Pamiętaj, że plik firebase.json może również zawierać konfiguracje innych usług Firebase .

Wdrożoną zawartość firebase.json możesz sprawdzić za pomocą interfejsu Hosting REST API .

Priorytet odpowiedzi Hostingu

Różne opcje konfiguracji Hostingu Firebase opisane na tej stronie mogą czasami się pokrywać. W przypadku konfliktu Hosting określa odpowiedź, stosując następującą kolejność priorytetów:

  1. Zarezerwowane przestrzenie nazw zaczynające się od segmentu ścieżki /__/*
  2. Skonfigurowane przekierowania
  3. Treść statyczna w ścisłym dopasowaniu
  4. Skonfigurowane przepisywania
  5. Niestandardowa strona 404
  6. Domyślna strona 404

Jeśli korzystasz z i18n rewrites , kolejność priorytetów w dopasowaniu ścisłym i obsługi 404 zostanie rozszerzona, aby uwzględnić Twoją „treść i18n”.

Określ, które pliki do wdrożenia

Atrybuty domyślne — public i ignore — zawarte w domyślnym pliku firebase.json definiują, które pliki z katalogu projektu powinny zostać wdrożone w projekcie Firebase.

Domyślna konfiguracja hosting w pliku firebase.json wygląda tak:

"hosting": {
  "public": "public",  // the only required attribute for Hosting
  "ignore": [
    "firebase.json",
    "**/.*",
    "**/node_modules/**"
  ]
}

publiczny

Wymagany
Atrybut public określa katalog do wdrożenia w Hostingu Firebase. Wartość domyślna to katalog o nazwie public , ale możesz określić ścieżkę dowolnego katalogu, o ile istnieje w katalogu projektu.

Poniżej znajduje się domyślna określona nazwa katalogu do wdrożenia:

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

  // ...
}

Możesz zmienić wartość domyślną na katalog, który chcesz wdrożyć:

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

  // ...
}

ignorować

Opcjonalny
Atrybut ignore określa pliki do zignorowania podczas wdrażania. Może zająć glob w taki sam sposób, w jaki Git obsługuje .gitignore .

Poniżej znajdują się wartości domyślne plików do zignorowania:

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

Dostosuj stronę 404/Nie znaleziono

Opcjonalny
Możesz wyświetlić niestandardowy błąd 404 Not Found , gdy użytkownik próbuje uzyskać dostęp do nieistniejącej strony.

Utwórz nowy plik w public katalogu swojego projektu , nazwij go 404.html , a następnie dodaj do pliku niestandardową treść 404 Not Found .

Hosting Firebase wyświetli zawartość tej niestandardowej strony 404.html , jeśli przeglądarka wyzwoli błąd 404 Not Found w Twojej domenie lub subdomenie.

Skonfiguruj przekierowania

Opcjonalny
Użyj przekierowania adresu URL, aby zapobiec niedziałającym linkom po przeniesieniu strony lub skrócić adresy URL. Na przykład możesz przekierować przeglądarkę z example.com/team na example.com/about.html .

Określ przekierowania adresów URL, tworząc atrybut redirects , który zawiera tablicę obiektów (nazywanych „regułami przekierowań”). W każdej regule określ wzorzec adresu URL, który po dopasowaniu do ścieżki adresu URL żądania powoduje, że Hosting odpowiada przekierowaniem do określonego docelowego adresu URL.

Oto podstawowa struktura atrybutu redirects . Ten przykład przekierowuje żądania do /foo , tworząc nowe żądanie do /bar .

"hosting": {
  // ...

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

Atrybut redirects zawiera tablicę reguł przekierowań, gdzie każda reguła musi zawierać pola z poniższej tabeli.

Hosting Firebase porównuje wartość source lub regex ze wszystkimi ścieżkami adresów URL na początku każdego żądania (zanim przeglądarka określi, czy plik lub folder istnieje w tej ścieżce). Jeśli zostanie znalezione dopasowanie, serwer pochodzenia Firebase Hosting wysyła odpowiedź przekierowania HTTPS, informującą przeglądarkę o konieczności wykonania nowego żądania pod destination adresem URL.

Pole Opis
redirects
source (zalecane)
lub regex

Wzorzec adresu URL, który po dopasowaniu do początkowego adresu URL żądania powoduje, że Hosting stosuje przekierowanie

destination

Statyczny adres URL, pod którym przeglądarka powinna wysłać nowe żądanie

Ten adres URL może być ścieżką względną lub bezwzględną.

type

Kod odpowiedzi HTTPS

  • Użyj typu 301 dla „Przeniesione na stałe”
  • Użyj typu 302 dla „Znaleziono” (przekierowanie tymczasowe)

Przechwytuj segmenty adresów URL do przekierowań

Opcjonalny
Czasami może być konieczne przechwycenie określonych segmentów wzorca adresu URL reguły przekierowania (wartość source lub regex ), a następnie ponowne użycie tych segmentów w ścieżce destination reguły.

Konfiguruj przepisywanie

Opcjonalny
Użyj przepisania, aby wyświetlić tę samą treść dla wielu adresów URL. Przepisywanie jest szczególnie przydatne w przypadku dopasowywania wzorców, ponieważ można zaakceptować dowolny adres URL pasujący do wzorca i pozwolić kodowi po stronie klienta decydować, co wyświetlić.

Możesz także użyć funkcji przepisywania, aby obsługiwać aplikacje, które używają do nawigacji HTML5 pushState . Gdy przeglądarka spróbuje otworzyć ścieżkę URL, która pasuje do określonego wzorca adresu URL source lub regex , przeglądarka otrzyma zamiast tego zawartość pliku pod destination adresem URL.

Określ przepisywanie adresów URL, tworząc atrybut rewrites , który zawiera tablicę obiektów (zwanych „regułami przepisywania”). W każdej regule określ wzorzec adresu URL, który po dopasowaniu do ścieżki adresu URL żądania powoduje, że usługa Hosting odpowiada tak, jakby usługa otrzymała określony docelowy adres URL.

Oto podstawowa struktura atrybutu rewrites . Ten przykład wyświetla index.html dla żądań do plików lub katalogów, które nie istnieją.

"hosting": {
  // ...

  // Serves index.html for requests to files or directories that do not exist
  "rewrites": [ {
    "source": "**",
    "destination": "/index.html"
  } ]
}

Atrybut rewrites zawiera tablicę reguł przepisywania, gdzie każda reguła musi zawierać pola z poniższej tabeli.

Hosting Firebase stosuje regułę ponownego zapisywania tylko wtedy, gdy plik lub katalog nie istnieje w ścieżce adresu URL zgodnej z określonym wzorcem adresu URL source lub regex . Gdy żądanie wyzwala regułę ponownego zapisu, przeglądarka zwraca rzeczywistą zawartość określonego pliku destination zamiast przekierowania HTTP.

Pole Opis
rewrites
source (zalecane)
lub regex

Wzorzec adresu URL, który po dopasowaniu do początkowego adresu URL żądania powoduje, że Hosting stosuje przepisanie

destination

Plik lokalny, który musi istnieć

Ten adres URL może być ścieżką względną lub bezwzględną.

Bezpośrednie żądania do funkcji

Możesz użyć rewrites , aby obsługiwać funkcję z adresu URL w Hostingu Firebase. Poniższy przykład to fragment z udostępniania zawartości dynamicznej za pomocą Cloud Functions .

Na przykład, aby skierować wszystkie żądania ze strony /bigben w Twojej witrynie Hosting w celu wykonania funkcji 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)
  } ]
}

Po dodaniu tej reguły przepisywania i wdrożeniu w Firebase (przy użyciu firebase deploy ), Twoja funkcja będzie dostępna pod następującymi adresami URL:

  • Twoje subdomeny Firebase:
    PROJECT_ID .web.app/bigben i PROJECT_ID .firebaseapp.com/bigben

  • Wszystkie połączone domeny niestandardowe :
    CUSTOM_DOMAIN /bigben

Podczas przekierowywania żądań do funkcji z Hosting, obsługiwane metody żądań HTTP to GET , POST , HEAD , PUT , DELETE , PATCH i OPTIONS . Inne metody, takie jak REPORT lub PROFIND , nie są obsługiwane.

Kieruj żądania do kontenera Cloud Run

Aby uzyskać dostęp do kontenera Cloud Run z adresu URL w Hostingu rewrites , możesz użyć opcji ponownego zapisu. Poniższy przykład to fragment z udostępniania treści dynamicznych za pomocą Cloud Run .

Na przykład, aby skierować wszystkie żądania ze strony /helloworld w Twojej witrynie Hosting w celu uruchomienia i uruchomienia instancji kontenera 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)
   }
 } ]
}

Po dodaniu tej reguły przepisywania i wdrożeniu w Firebase (przy użyciu firebase deploy ) Twój obraz kontenera będzie dostępny pod następującymi adresami URL:

  • Twoje subdomeny Firebase:
    PROJECT_ID .web.app/helloworld i PROJECT_ID .firebaseapp.com/helloworld

  • Wszystkie połączone domeny niestandardowe :
    CUSTOM_DOMAIN /helloworld

Podczas przekierowywania żądań do kontenerów Cloud Run z Hostingiem obsługiwane metody żądań HTTP to GET , POST , HEAD , PUT , DELETE , PATCH i OPTIONS . Inne metody, takie jak REPORT lub PROFIND , nie są obsługiwane.

Obecnie możesz używać przepisywania Cloud Run z Hostingiem w następujących regionach:

  • 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

Możesz użyć rewrites do tworzenia niestandardowych linków dynamicznych domeny. Odwiedź dokumentację Dynamic Links, aby uzyskać szczegółowe informacje o konfigurowaniu domeny niestandardowej dla Dynamic Links .

  • Używaj domeny niestandardowej tylko dla Linków dynamicznych

    "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
      } ]
    }
    
  • Określ niestandardowe prefiksy ścieżki domeny, które mają być używane dla 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
      } ]
    }
    

Skonfigurowanie Linków dynamicznych w pliku firebase.json wymaga spełnienia następujących warunków:

Pole Opis
appAssociation

Musi być ustawiony na AUTO

  • Jeśli nie uwzględnisz tego atrybutu w konfiguracji, wartością domyślną dla appAssociation jest AUTO .
  • Ustawiając ten atrybut na AUTO , Hosting może dynamicznie generować assetlinks.json i apple-app-site-association , gdy są wymagane.
rewrites
source

Ścieżka, której chcesz użyć dla Linków dynamicznych

W przeciwieństwie do reguł przepisywania ścieżek do adresów URL reguły przepisywania linków dynamicznych nie mogą zawierać wyrażeń regularnych.

dynamicLinks Musi być ustawiony na true

Skonfiguruj nagłówki

Opcjonalny
Nagłówki umożliwiają klientowi i serwerowi przekazywanie dodatkowych informacji wraz z żądaniem lub odpowiedzią. Niektóre zestawy nagłówków mogą wpływać na sposób, w jaki przeglądarka obsługuje stronę i jej zawartość, w tym kontrolę dostępu, uwierzytelnianie, buforowanie i kodowanie.

Określ niestandardowe, specyficzne dla pliku nagłówki odpowiedzi, tworząc atrybut headers zawierający tablicę obiektów nagłówka. W każdym obiekcie określ wzorzec adresu URL, który w przypadku dopasowania do ścieżki adresu URL żądania powoduje, że Hosting stosuje określone niestandardowe nagłówki odpowiedzi.

Oto podstawowa struktura atrybutu headers . Ten przykład stosuje nagłówek CORS do wszystkich plików czcionek.

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

Atrybut headers zawiera tablicę definicji, gdzie każda definicja musi zawierać pola z poniższej tabeli.

Pole Opis
headers
source (zalecane)
lub regex

Wzorzec adresu URL, który po dopasowaniu do początkowego adresu URL żądania powoduje, że Hosting stosuje niestandardowy nagłówek

Aby utworzyć nagłówek pasujący do niestandardowej strony 404 , użyj 404.html jako source lub wartości regex .

tablica (pod-) headers

Niestandardowe nagłówki stosowane przez Hosting do ścieżki żądania

Każdy podnagłówek musi zawierać parę key i value (patrz kolejne dwa wiersze).

key Nazwa nagłówka, na przykład Cache-Control
value Wartość nagłówka, na przykład max-age=7200

Więcej informacji na temat Cache-Control można znaleźć w sekcji Hosting, w której opisano udostępnianie zawartości dynamicznej i hosting mikrousług. Możesz również dowiedzieć się więcej o nagłówkach CORS .

Kontroluj rozszerzenia .html

Opcjonalny
Atrybut cleanUrls pozwala kontrolować, czy adresy URL powinny zawierać rozszerzenie .html .

Gdy true , Hosting automatycznie usuwa rozszerzenie .html z przesłanych adresów URL plików. Jeśli w żądaniu zostanie dodane rozszerzenie .html , Hosting wykonuje przekierowanie 301 do tej samej ścieżki, ale eliminuje rozszerzenie .html .

Oto jak kontrolować włączanie .html do adresów URL, dołączając atrybut cleanUrls :

"hosting": {
  // ...

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

Kontroluj końcowe ukośniki

Opcjonalny
Atrybut trailingSlash umożliwia kontrolowanie, czy statyczne adresy URL treści powinny zawierać końcowe ukośniki.

  • Gdy true , Hosting przekierowuje adresy URL, aby dodać końcowy ukośnik.
  • Gdy false , Hosting przekierowuje adresy URL w celu usunięcia końcowego ukośnika.
  • Gdy nie jest określony, Hosting używa tylko końcowych ukośników dla plików indeksu katalogów (na przykład about/index.html ).

Oto jak kontrolować końcowe ukośniki, dodając atrybut trailingSlash :

"hosting": {
  // ...

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

Atrybut trailingSlash nie wpływa na ponowne zapisy w treści dynamicznej obsługiwanej przez Cloud Functions lub Cloud Run.

Dopasowanie wzorca glob

Opcje konfiguracji Hostingu Firebase w dużym stopniu wykorzystują notację dopasowywania wzorców glob z extglob, podobnie jak Git obsługuje reguły gitignore , a uchwyty Bower ignore reguły. Ta strona wiki jest bardziej szczegółowym odniesieniem, ale poniżej znajdują się objaśnienia przykładów użytych na tej stronie:

  • firebase.json — Dopasowuje tylko plik firebase.json w katalogu głównym katalogu public

  • ** — Dopasowuje dowolny plik lub folder w dowolnym podkatalogu

  • * — Dopasowuje tylko pliki i foldery w katalogu głównym katalogu public

  • **/.* — Dopasowuje dowolny plik zaczynający się od . (zwykle ukryte pliki, jak w folderze .git ) w dowolnym podkatalogu

  • **/node_modules/** — dopasowuje dowolny plik lub folder w dowolnym podkatalogu folderu node_modules , który sam może znajdować się w dowolnym podkatalogu katalogu public

  • **/*.@(jpg|jpeg|gif|png) — dopasowuje dowolny plik w dowolnym podkatalogu, który kończy się dokładnie jednym z następujących: .jpg , .jpeg , .gif lub .png

Przykład pełnej konfiguracji hostingu

Poniżej znajduje się pełny przykład konfiguracji firebase.json dla Hostingu Firebase. Pamiętaj, że plik firebase.json może również zawierać konfiguracje innych usług 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",

  }
}