Skonfiguruj zachowanie hostingu

Dzięki Hostingowi Firebase możesz skonfigurować niestandardowe zachowanie hostingu dla żądań kierowanych 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.

• Udostępnij dostosowaną stronę 404/Not Found. Naucz się jak.

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

• Skonfiguruj rewrites do dowolnego z poniższych celów:

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

  • Obsługuj funkcję lub uzyskaj dostęp do kontenera Cloud Run z hostującego adresu URL. Dowiedz się, jak: funkcja lub kontener .

  • Utwórz link dynamiczny domeny niestandardowej. Naucz się jak.

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

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

Gdzie definiujesz swoją 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) można znaleźć na dole tej strony. Pamiętaj, że plik firebase.json może również zawierać konfiguracje innych usług Firebase .

Możesz sprawdzić wdrożoną zawartość firebase.json za pomocą Hosting REST API .

Kolejność priorytetów odpowiedzi Hostingu

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

1. Zarezerwowane przestrzenie nazw, które zaczynają się od /__/* segmentu ścieżki
2. Skonfigurowane przekierowania
3. Zawartość statyczna z dopasowaniem ścisłym
4. Skonfigurowane przepisywanie
5. Niestandardowa strona 404
6. Domyślna strona 404

Jeśli korzystasz z przepisywania i18n , kolejność dopasowywania dokładnego i priorytetu obsługi 404 jest rozszerzona, aby pomieścić „treść 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 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ścią domyślną jest katalog o nazwie public , ale można określić ścieżkę dowolnego katalogu, o ile istnieje on w katalogu projektu.

Poniżej podano domyślną nazwę 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 przyjmować globy w taki sam sposób, w jaki Git obsługuje .gitignore .

Poniżej przedstawiono 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
  ]
}

Dostosuj stronę 404/Nie znaleziono

Opcjonalny
Możesz wyświetlać niestandardowy błąd 404 Not Found , gdy użytkownik próbuje uzyskać dostęp do strony, która nie istnieje.

Utwórz nowy plik w public katalogu swojego projektu , nazwij go 404.html , a następnie dodaj do niego niestandardową zawartość 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.

Skonfiguruj przekierowania

Opcjonalny
Użyj przekierowania adresu URL, aby zapobiec uszkodzeniu linków, jeśli przeniosłeś stronę, lub aby skrócić adresy URL. Możesz na przykład przekierować przeglądarkę z example.com/team na example.com/about.html .

Określ przekierowania adresów URL, tworząc atrybut redirects zawierający tablicę obiektów (zwanych „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 przez utworzenie 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, z których każda musi zawierać pola z poniższej tabeli.

Firebase Hosting porównuje source lub wartość regex ze wszystkimi ścieżkami URL na początku każdego żądania (zanim przeglądarka ustali, 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ę, aby wysłała nowe żądanie pod destination adresem URL.

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.

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

Opcjonalny
Użyj przepisywania, 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ć, aby kod po stronie klienta decydował, co ma być wyświetlane.

Możesz także użyć przepisywania, aby obsługiwać aplikacje korzystające z HTML5 pushState do nawigacji. Gdy przeglądarka próbuje otworzyć ścieżkę adresu URL zgodną z określonym wzorcem adresu URL source lub regex , zamiast tego przeglądarka otrzyma zawartość pliku pod destination adresem URL.

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

Oto podstawowa struktura atrybutu rewrites . Ten przykład obsługuje 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"
  } ]
}

"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, gdzie 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, która pasuje do określonego wzorca source lub regex . Gdy żądanie uruchamia regułę przepisywania, przeglądarka zwraca rzeczywistą zawartość określonego pliku destination zamiast przekierowania HTTP.

Bezpośrednie żądania do funkcji

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

Na przykład, aby skierować wszystkie żądania ze strony /bigben w Twojej witrynie hostingowej do 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)
    "pinTag": true           // optional (see note below)
  } ]
}

Po dodaniu tej reguły przepisywania i wdrożeniu w Firebase (przy użyciu firebase deploy ) Twoja funkcja jest osiągalna za pośrednictwem następujących adresów URL:

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

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

Podczas przekierowywania żądań do funkcji 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.

Kieruj żądania do kontenera Cloud Run

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

Na przykład, aby skierować wszystkie żądania ze strony /helloworld w Twojej witrynie hostingowej, aby uruchomić i uruchomić instancję 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 ) obraz kontenera jest dostępny za pośrednictwem następujących adresów URL:

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

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

Podczas przekierowywania żądań do kontenerów Cloud Run za pomocą Hostingu 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

Utwórz niestandardowe linki dynamiczne domeny

Możesz użyć rewrites , aby utworzyć niestandardowe linki dynamiczne domeny. Odwiedź dokumentację Linków dynamicznych, aby uzyskać szczegółowe informacje na temat konfigurowania domeny niestandardowej dla Linków dynamicznych .

• Używaj domeny niestandardowej tylko w przypadku 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żek domen, które mają być używane w przypadku linków 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:

Skonfiguruj nagłówki

Opcjonalny
Nagłówki umożliwiają klientowi i serwerowi przekazanie 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 , 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 spowoduje, że Hosting zastosuje określone niestandardowe nagłówki odpowiedzi.

Oto podstawowa struktura atrybutu headers . W tym przykładzie zastosowano nagłówek CORS dla 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, gdzie każda definicja musi zawierać pola z poniższej tabeli.

Możesz dowiedzieć się więcej o Cache-Control w sekcji Hosting, która opisuje udostępnianie zawartości dynamicznej i hosting mikrousług. Możesz także dowiedzieć się więcej o nagłówkach CORS .

Kontroluj rozszerzenia .html

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

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

Oto jak kontrolować dołą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 pozwala kontrolować, czy statyczne adresy URL treści powinny zawierać końcowe ukośniki.

• Gdy true , Hosting przekierowuje adresy URL, dodając końcowy ukośnik.
• W przypadku false Hosting przekierowuje adresy URL, usuwając końcowy ukośnik.
• Gdy nie jest określony, Hosting używa końcowych ukośników tylko dla plików indeksu katalogów (na przykład about/index.html ).

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

"hosting": {
  // ...

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

Atrybut trailingSlash nie wpływa na ponowne zapisywanie treści dynamicznych udostępnianych przez Cloud Functions lub Cloud Run.

Dopasowanie wzorca globu

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

• firebase.json — Pasuje tylko do pliku 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 rozpoczynają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 poniższych: .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",

  }
}