Skonfiguruj zachowanie Hostingu

Hosting Firebase pozwala skonfigurować niestandardowe działanie hostowania żądań do witryny.

Co możesz skonfigurować pod kątem Hostingu?

• Określ, które pliki w lokalnym katalogu projektów chcesz wdrożyć w Hostingu Firebase. Więcej informacji

• Wyświetla dostosowaną stronę 404/nie znaleziono. Więcej informacji

• Skonfiguruj redirects dla przeniesionych lub usuniętych stron. Więcej informacji

• Skonfiguruj usługę rewrites w dowolnym z tych celów:

  • Wyświetlaj tę samą treść pod wieloma adresami URL. Więcej informacji

  • Obsługuj funkcję lub uzyskaj dostęp do kontenera Cloud Run z adresu URL Hostingu. Więcej informacji: funkcja lub kontener.

  • Utwórz link dynamiczny domeny niestandardowej. Więcej informacji

• Dodaj atrybut headers, aby przekazywać dodatkowe informacje o żądaniu lub odpowiedzi, takie jak sposób obsługi strony i jej zawartości (uwierzytelnianie, przechowywanie w pamięci podręcznej, kodowanie itp.). Więcej informacji

• Konfiguruj korekty internacjonalizacji (i18n), aby wyświetlać określone treści na podstawie preferencji językowych użytkownika lub kraju. Dowiedz się, jak to zrobić (inna strona).

Gdzie definiujesz konfigurację hostingu?

Definiujesz konfigurację Hostingu Firebase w pliku firebase.json. Po uruchomieniu polecenia firebase init Firebase automatycznie tworzy plik firebase.json w katalogu głównym Twojego katalogu projektu.

Przykład pełnej konfiguracji firebase.json (obejmujący tylko Hosting Firebase) znajdziesz na dole tej strony. Pamiętaj, że plik firebase.json może też zawierać konfiguracje innych usług Firebase.

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

Kolejność priorytetów odpowiedzi Hostingu

Różne opcje konfiguracji Hostingu Firebase opisane na tej stronie mogą się czasami pokrywać. W przypadku konfliktu Hosting określa odpowiedź według priorytetu w następujący sposób:

1. Zarezerwowane przestrzenie nazw, które zaczynają się od segmentu ścieżki /__/*
2. Skonfigurowane przekierowania
3. Ścisłe dopasowanie treści statycznej
4. Skonfigurowane przepisy
5. Strona Niestandardowa strona 404
6. Domyślna strona 404

Jeśli korzystasz z przepisów i18n, zakres dopasowania ścisłego i priorytetu obsługi 404 zostanie rozszerzony, aby uwzględnić Twoje „treści i18n”.

Określ pliki do wdrożenia

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

publiczna

Wymagany
Atrybut public określa, który katalog ma zostać wdrożony w Hostingu Firebase. Wartość domyślna to katalog o nazwie public, ale możesz podać ścieżkę dowolnego katalogu, o ile istnieje on 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"

  // ...
}

ignoruj

Opcjonalny
Atrybut ignore określa pliki, które mają być ignorowane podczas wdrażania. Może zajmować glob w taki sam sposób jak Git obsługuje .gitignore.

Te wartości domyślne, które mają być ignorowane przez pliki:

"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świetlać niestandardowy błąd 404 Not Found, gdy użytkownik próbuje otworzyć stronę, która nie istnieje.

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

Hosting Firebase 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 uszkodzonym linkom w przypadku przeniesienia strony lub skrócenia adresów URL. Możesz na przykład przekierować przeglądarkę z adresu example.com/team na adres example.com/about.html.

Określ przekierowania adresów URL, tworząc atrybut redirects zawierający tablicę obiektów (nazywanych „regułami przekierowania”). W każdej regule określ wzorzec adresu URL, który po dopasowaniu do ścieżki adresu URL żądania powoduje, że Hosting w odpowiedzi przesyła przekierowanie na określony docelowy adres URL.

Oto podstawowa struktura atrybutu redirects. W tym przykładzie żądania są przekierowywane do /foo 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
  } ]
}

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

Atrybut redirects zawiera tablicę reguł przekierowania, przy czym 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 sprawdzi, czy w danej ścieżce znajduje się plik lub folder). W przypadku znalezienia dopasowania serwer źródłowy Hostingu Firebase wysyła odpowiedź o przekierowaniu HTTPS, informując przeglądarkę, że ma wysłać nowe żądanie pod adresem URL destination.

Rejestrowanie segmentów adresów URL na potrzeby przekierowań

Opcjonalnie
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.

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

Skonfiguruj przepisy

Opcjonalnie
Użyj przepisywania, aby wyświetlić tę samą treść pod wieloma adresami URL. Modyfikacje są szczególnie przydatne w przypadku dopasowywania do wzorca, ponieważ możesz zaakceptować dowolny adres URL pasujący do wzorca, a kod po stronie klienta decyduje, co ma się wyświetlać.

Możesz również użyć przeredagowania, by umożliwić obsługę aplikacji, które korzystają z nawigacji w trybie HTML5 pushState. Gdy przeglądarka próbuje otworzyć ścieżkę adresu URL pasującą do określonego wzorca adresu URL source lub regex, przeglądarka odczytuje zawartość pliku pod adresem URL destination.

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

Oto podstawowa struktura atrybutu rewrites. Ten przykład obsługuje index.html w przypadku żądań wysyłanych do nieistniejących plików lub katalogów.

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

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

Hosting Firebase stosuje regułę przepisywania tylko wtedy, gdy plik lub katalog nie istnieje w ścieżce adresu URL pasującej do określonego wzorca adresu URL source lub regex. Gdy żądanie aktywuje regułę przepisywania, przeglądarka zwraca rzeczywistą zawartość określonego pliku destination zamiast przekierowania HTTP.

Bezpośrednie żądania do funkcji

Za pomocą rewrites możesz obsługiwać funkcję z adresu URL Hostingu Firebase. Poniższy przykład to fragment z wyświetlania treści dynamicznych za pomocą Cloud Functions.

Jeśli na przykład chcesz skierować wszystkie żądania ze strony /bigben w Twojej 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 przepisywania i wdrożeniu jej w Firebase (przy użyciu firebase deploy) funkcja będzie dostępna pod tymi 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 Hostingu obsługiwane metody żądań HTTP to GET, POST, HEAD, PUT, DELETE, PATCH i OPTIONS. Inne metody, takie jak REPORT czy PROFIND, nie są obsługiwane.

Bezpośrednie żądania do kontenera Cloud Run

Za pomocą rewrites możesz uzyskać dostęp do kontenera Cloud Run z adresu URL Hostingu Firebase. Poniższy przykład to fragment z wyświetlania treści dynamicznych za pomocą Cloud Run.

Aby na przykład przekierować wszystkie żądania ze strony /helloworld w 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 obrazu kontenera w Firebase (przy użyciu firebase deploy) obraz kontenera będzie dostępny pod tymi adresami URL:

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

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

Gdy przekierowujesz żądania do kontenerów Cloud Run z użyciem Hostingu, obsługiwane metody żądań HTTP to GET, POST, HEAD, PUT, DELETE, PATCH i OPTIONS. Inne metody, takie jak REPORT czy PROFIND, nie są obsługiwane.

Aby uzyskać najlepszą wydajność, kolokuj usługę Cloud Run z usługą Hosting przy użyciu tych regionów:

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

Przepisywanie z usługi Hosting do Cloud Run jest 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

Tworzenie linków dynamicznych dla domen niestandardowych

Możesz użyć usługi rewrites, by utworzyć linki dynamiczne dla domeny niestandardowej. Szczegółowe informacje o konfigurowaniu niestandardowej domeny na potrzeby Linków dynamicznych znajdziesz w dokumentacji linków dynamicznych.

• Użyj własnej domeny tylko w linkach 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żek domeny do użycia w Linkach dynamicznych

  "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 tych ustawień:

Skonfiguruj nagłówki

Opcjonalne
Nagłówki pozwalają klientowi i serwerowi przekazać dodatkowe informacje wraz z żądaniem lub odpowiedzią. Niektóre zestawy nagłówków mogą wpływać na sposób obsługi strony i jej zawartości przez przeglądarkę, w tym na kontrolę dostępu, uwierzytelnianie, przechowywanie w pamięci podręcznej i kodowanie.

Aby określić niestandardowe nagłówki odpowiedzi związane z konkretnymi plikami, utwórz atrybut headers, który zawiera tablicę obiektów nagłówka. W każdym obiekcie określ wzorzec adresu URL, który po dopasowaniu do ścieżki adresu URL żądania powoduje, że Hosting stosuje określone niestandardowe nagłówki odpowiedzi.

Oto podstawowa struktura atrybutu headers. W tym przykładzie zastosowano 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": "*"
    } ]
  } ]
}

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

Atrybut headers zawiera tablicę definicji, z których każda definicja musi obejmować pola z poniższej tabeli.

Więcej informacji o Cache-Control znajdziesz w sekcji dotyczącej hostowania treści dynamicznych i mikroserwisów. Możesz też dowiedzieć się więcej o nagłówkach CORS.

Zarządzaj rozszerzeniami .html

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

Gdy true, Hosting automatycznie usuwa rozszerzenie .html z przesłanych adresów URL plików. Jeśli do żądania zostanie dodane rozszerzenie .html, Hosting wykonuje przekierowanie 301 na tę samą ścieżkę, ale eliminuje rozszerzenie .html.

Aby kontrolować uwzględnianie elementu .html w adresach URL za pomocą atrybutu cleanUrls:

"hosting": {
  // ...

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

Steruj końcowym ukośnikami

Opcjonalny
Atrybut trailingSlash pozwala określić, czy adresy URL treści statycznych powinny zawierać ukośniki końcowe.

• Gdy true, Hosting przekierowuje adresy URL, aby dodać na końcu ukośnik.
• Gdy false, Hosting przekierowuje adresy URL, aby usunąć ukośnik na końcu.
• Jeśli nie określono inaczej, w przypadku plików indeksu katalogów (na przykład about/index.html) Hosting używa tylko ukośników końcowych.

Aby kontrolować końcowe ukośniki, dodaj atrybut trailingSlash:

"hosting": {
  // ...

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

Atrybut trailingSlash nie ma wpływu na przepisywanie treści dynamicznych obsługiwanych przez Cloud Functions lub Cloud Run.

Dopasowywanie wzorców glob

Opcje konfiguracji Hostingu Firebase w szerokim zakresie wykorzystują notację dopasowania wzorców glob z metodą extglob, podobnie jak w przypadku Gita obsługuje reguły gitignore, a Bower – reguły ignore. Ta strona wiki zawiera bardziej szczegółowe materiały, ale poniżej znajdziesz ich przykłady:

• firebase.json – dopasowuje tylko plik firebase.json znajdujący się w katalogu głównym katalogu public

• ** – dopasowuje dowolny plik lub folder w dowolnym podkatalogu.

• * – dopasowuje tylko pliki i foldery znajdujące się w katalogu głównym public

• **/.* – dopasowuje każdy plik zaczynający się od . (zwykle ukryte pliki, np. w folderze .git) w dowolnym podkatalogu

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

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

Przykład konfiguracji pełnego hostingu

Poniżej znajdziesz pełny przykład konfiguracji firebase.json dla Hostingu Firebase. 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",

  }
}