Skonfiguruj zachowanie Hostingu

Dzięki Firebase Hosting możesz skonfigurować niestandardowe zachowanie hostingu w przypadku żądań wysyłanych do Twojej witryny.

Co możesz skonfigurować w przypadku Hosting?

  • Określ, które pliki w lokalnym katalogu projektu chcesz wdrożyć na serwerFirebase Hosting. Dowiedz się, jak to zrobić

  • wyświetlać niestandardową stronę 404/Nie znaleziono; Dowiedz się, jak to zrobić

  • Skonfiguruj redirects na stronach, które zostały przeniesione lub usunięte. Dowiedz się, jak to zrobić

  • Skonfiguruj rewrites na potrzeby:

  • Dodaj headers, aby przekazać dodatkowe informacje o żądaniu lub odpowiedzi, np. o tym, jak przeglądarki powinny obsługiwać stronę i jej zawartość (uwierzytelnianie, buforowanie, kodowanie itp.). Dowiedz się, jak to zrobić

  • Skonfiguruj przekształcanie treści na potrzeby międzynarodowe (i18n), aby wyświetlać określone treści na podstawie ustawień języka lub kraju użytkownika. Dowiedz się, jak to zrobić (inna strona).

Gdzie definiujesz konfigurację Hosting?

Konfigurację Firebase Hosting definiujesz w pliku firebase.json. Gdy uruchomisz polecenie firebase init, Firebase automatycznie utworzy plik firebase.json w katalogu głównym katalogu projektu.

Poniżej znajdziesz przykład pełnej konfiguracji firebase.json (dotyczącej tylko Firebase Hosting). Pamiętaj, że plik firebase.json może też zawierać konfiguracje innych usług Firebase.

Za pomocą interfejsu Hosting API REST możesz sprawdzić wdrożony kontent firebase.json.

Zmieniono kolejność priorytetów odpowiedzi (Hosting)

Różne opcje konfiguracji Firebase Hosting opisane na tej stronie mogą się czasem pokrywać. W przypadku konfliktu Hosting określa odpowiedź zgodnie z tym priorytetem:

  1. Zarezerwowane przestrzenie nazw, które zaczynają się od segmentu ścieżki /__/*
  2. Skonfigurowane przekierowania
  3. Treści statyczne z dopasowaniem dokładnym
  4. Skonfigurowane przekierowania
  5. Niestandardowa strona 404
  6. Domyślna strona 404

Jeśli używasz przepisywania treści w języku międzynarodowym, zakres priorytetów obsługi dopasowania do wyrażenia w pełni i błędów 404 jest rozszerzony, aby uwzględnić „treści w języku międzynarodowym”.

Określanie plików do wdrożenia

Domyślne atrybuty public i ignore zawarte w domyślnym pliku firebase.json określają, które pliki w katalogu projektu powinny zostać wdrożone do projektu 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/**"
  ]
}

publiczna

Wymagany
Atrybut public określa, do którego katalogu ma zostać wdrożony element Firebase Hosting. Wartość domyślna to katalog o nazwie public, ale możesz określić ścieżkę dowolnego katalogu, o ile istnieje on w katalogu projektu.

Oto domyślna nazwa katalogu, który chcesz wdrożyć:

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

  // ...
}

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

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

  // ...
}

ignorować

Opcjonalnie
Atrybut ignore określa pliki, które mają być ignorowane podczas wdrażania. Może ona przyjmować globy w taki sam sposób, w jaki Git obsługuje .gitignore.

Domyślne wartości 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
  ]
}

Dostosowywanie strony 404/Nie znaleziono

Opcjonalnie
Możesz wyświetlić niestandardowy błąd 404 Not Found, gdy użytkownik spróbuje otworzyć nieistniejącą stronę.

Utwórz nowy plik w katalogu public projektu, nadaj mu nazwę 404.html, a potem dodaj do niego niestandardową zawartość 404 Not Found.

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

Konfigurowanie przekierowań

Opcjonalnie
Użyj przekierowania adresu URL, aby zapobiec niedziałającym linkom po przeniesieniu strony lub skrócić adresy URL. Możesz na przykład przekierować przeglądarkę z adresu 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żdym regułach określ wzór adresu URL, który po dopasowaniu do ścieżki adresu URL żądania powoduje, że reguła Hosting odpowiada przekierowaniem do określonego adresu URL docelowego.

Oto podstawowa struktura atrybutu redirects. W tym przykładzie żądania do /foo są przekierowywane przez wysłanie nowego żądania 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ł przekierowania, w której każda reguła musi zawierać pola podane w tabeli poniżej.

Firebase Hosting porównuje wartość source lub regex ze wszystkimi ścieżkami adresów URL na początku każdej prośby (zanim przeglądarka zweryfikuje, czy istnieje plik lub folder na tej ścieżce). Jeśli zostanie znalezione dopasowanie, serwer źródłowy Firebase Hosting wysyła odpowiedź z przekierowaniem HTTPS, informując przeglądarkę, że ma wysłać nowe żądanie pod adresem URL destination.

Pole Opis
redirects
source (zalecane)
lub regex

Wzorzec adresu URL, który po dopasowaniu do początkowego adresu URL żądania powoduje zastosowanie przekierowania.Hosting
destination

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

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

Kod odpowiedzi HTTPS

  • W przypadku wartości „Przeniesiono na stałe” użyj typu 301.
  • Użyj typu 302 dla „Found” (tymczasowe przekierowanie).

Przechwytywanie segmentów adresów URL w przypadku przekierowań

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

Konfigurowanie przekierowań

Opcjonalne
Użyj przekierowania, aby wyświetlać tę samą treść dla wielu adresów URL. Przekierowania są szczególnie przydatne w przypadku dopasowywania do wzoru, ponieważ możesz zaakceptować dowolny adres URL, który pasuje do wzoru, i pozwolić kodom po stronie klienta na podjęcie decyzji, co wyświetlić.

Możesz też używać przekierowań do obsługi aplikacji, które do nawigacji korzystają z pushState HTML5. Gdy przeglądarka spróbuje otworzyć ścieżkę adresu URL pasującą do wzorca adresu source lub regex, zamiast tego otrzyma zawartość pliku pod adresem destination.

Określ przekierowania adresów URL, tworząc atrybut rewrites, który zawiera tablicę obiektów (nazywanych „regułami przekierowania”). W każdym regułach określ wzór adresu URL, który po dopasowaniu do ścieżki adresu URL żądania powoduje, że Hosting reaguje tak, jakby usługa otrzymała określony docelowy adres URL.

Oto podstawowa struktura atrybutu rewrites. W tym przykładzie serwer wysyła odpowiedźindex.html w przypadku żądań dotyczących 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ł przekierowania, w której każda reguła musi zawierać pola podane w tabeli poniżej.

Firebase Hosting stosuje regułę przekierowania tylko wtedy, gdy plik lub katalog nie istnieje na ścieżce adresu URL, która pasuje do wzorca adresu source lub regex. Gdy żądanie uruchamia regułę przekierowania, przeglądarka zwraca rzeczywistą zawartość pliku destination, a nie przekierowanie HTTP.

Pole Opis
rewrites
source (zalecane)
lub regex

Wzorzec adresu URL, który po dopasowaniu do początkowego adresu URL żądania powoduje zastosowanie przekierowaniaHosting
destination

Plik lokalny, który musi istnieć.

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

Przekierowywanie żądań do funkcji

Możesz użyć funkcji rewrites, aby wywołać funkcję z adresu URL Firebase Hosting. Poniższy przykład to fragment wyświetlania treści dynamicznych za pomocą Cloud Functions.

Aby np. przekierowywać wszystkie żądania ze strony /bigben w witrynie Hosting do wykonania funkcji 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)
    }
  } ]
}

Po dodaniu tej reguły przekierowania i wdrożeniu funkcji w Firebase (za pomocą firebase deploy) będzie ona dostępna pod tymi adresami URL:

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

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

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

Żądania kierowane bezpośrednio do kontenera Cloud Run

Za pomocą rewrites możesz uzyskać dostęp do kontenera Cloud Run z poziomu adresu URL Firebase Hosting. Ten przykład to fragment kodu, który wyświetla zawartość dynamiczną za pomocą funkcji Cloud Run.

Aby na przykład kierować wszystkie żądania ze strony /helloworld w witrynie Hosting do uruchamiania i uruchamiania 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 przekierowania i wdrożeniu na Firebase (za pomocą firebase deploy) 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

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

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

Aby uzyskać najlepszą wydajność, umieść usługę Cloud Run w usługach Hosting w tych regionach:

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

Przekierowania z formatu Hosting na format Cloud Run są obsługiwane w tych regionach:

  • 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

Możesz użyć rewrites, aby utworzyć domenę niestandardową Dynamic Links. Szczegółowe informacje o konfigurowaniu domeny niestandardowej w usłudze Dynamic Links znajdziesz w dokumentacji Dynamic Links.

  • Używaj domeny niestandardowej tylko do obsługi 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
  } ]
}

  • Określ prefiksy ścieżek domen niestandardowych, których chcesz używać w przypadku 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
  } ]
}

Aby skonfigurować Dynamic Links w pliku firebase.json, musisz wykonać te czynności:

Pole Opis
appAssociation

Musi mieć wartość AUTO

  • Jeśli nie uwzględnisz tego atrybutu w konfiguracji, domyślnie appAssociation będzie równe AUTO.
  • Gdy ten atrybut jest ustawiony na AUTO, usługa Hosting może dynamicznie generować pliki assetlinks.json i apple-app-site-association na żądanie.
rewrites
source

Ścieżka, której chcesz użyć w przypadku Dynamic Links

W odróżnieniu od reguł, które przepisują ścieżki na adresy URL, reguły przepisywania dla Dynamic Links nie mogą zawierać wyrażeń regularnych.

dynamicLinks Musi mieć wartość true

Konfigurowanie nagłówków

Opcjonalne
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 nagłówki odpowiedzi dotyczące konkretnego pliku, tworząc atrybut headers, który zawiera tablicę obiektów nagłówka. W każdym obiekcie podaj wzór adresu URL, który po dopasowaniu do ścieżki adresu URL żądania powoduje, że Hosting stosuje określone nagłówki odpowiedzi niestandardowej.

Oto podstawowa struktura atrybutu headers. W tym przykładzie nagłówek CORS jest stosowany 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, z których każda musi zawierać pola podane w tabeli poniżej.

Pole Opis
headers
source (zalecane)
lub regex

Wzorzec adresu URL, który po dopasowaniu do początkowego adresu URL żądania powoduje Hosting zastosowanie nagłówka niestandardowego

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

tablica (pod)headers

niestandardowe nagłówki, które Hosting stosuje do ścieżki żądania.

Każdy nagłówek podrzędny musi zawierać parę wartości key i value (patrz 2 kolejne wiersze).

key Nazwa nagłówka, np. Cache-Control
value Wartość nagłówka, np. max-age=7200

Więcej informacji o Cache-Control znajdziesz w sekcji Hosting, która opisuje dostarczanie treści dynamicznych i hostowanie mikrousług. Możesz też dowiedzieć się więcej o nagłówkach CORS.

Zarządzanie rozszerzeniami .html

Opcjonalny
Atrybut cleanUrls pozwala określić, czy adresy URL mają zawierać rozszerzenie .html.

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

Aby kontrolować uwzględnianie atrybutu .html w adresach URL, użyj atrybutu cleanUrls:

"hosting": {
  // ...

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

sterowanie ukośnikami na końcu,

Opcjonalny
Atrybut trailingSlash pozwala określić, czy adresy URL treści statycznych mają zawierać ukośniki.

  • Gdy true, Hosting przekierowuje adresy URL, aby dodać końcową ukośnicę.
  • Gdy false, Hosting usuwa końcowy ukośnik w adresach URL.
  • Jeśli nie zostanie podany, Hosting używa tylko tylnych ukośników w plikach indeksu katalogu (np. about/index.html).

Oto jak kontrolować ukośniki końcowe przez dodanie atrybutu trailingSlash:

"hosting": {
  // ...

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

Atrybut trailingSlash nie ma wpływu na przekierowania do treści dynamicznych wyświetlanych przez Cloud Functions lub Cloud Run.

Dopasowywanie do wzorca glob

Opcje konfiguracji Firebase Hosting korzystają z notacji dopasowania wzorca glob za pomocą extglob, podobnie jak Git obsługuje reguły gitignore, a Bower – reguły ignore. Ta strona wiki zawiera bardziej szczegółowe informacje, ale poniżej znajdziesz wyjaśnienia przykładów użytych na tej stronie:

  • firebase.json – pasuje tylko do pliku firebase.json w katalogu głównym public.

  • ** – pasuje do dowolnego pliku lub folderu w dowolnym podkatalogu.

  • * – pasuje tylko do plików i folderów w katalogu głównym katalogu public.

  • **/.* – pasuje do każdego pliku zaczynającego się od . (zwykle ukryte pliki, na przykład w folderze .git) w dowolnym podkatalogu.

  • **/node_modules/** – pasuje do dowolnego pliku lub folderu w dowolnym podkatalogu folderu node_modules, który może znajdować się w dowolnym podkatalogu katalogu public.

  • **/*.@(jpg|jpeg|gif|png) – dopasowuje się do dowolnego pliku w dowolnym podkatalogu, który kończy się dokładnie jednym z tych elementów: .jpg, .jpeg, .gif lub .png.

Przykładowa pełna konfiguracja Hosting

Poniżej znajdziesz przykład pełnej konfiguracji firebase.json w przypadku Firebase Hosting. Pamiętaj, że plik firebase.json może też 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",

  }
}