Catch up on highlights from Firebase at Google I/O 2023. Learn more

Настройка поведения хостинга

С помощью Firebase Hosting вы можете настроить индивидуальное поведение хостинга для запросов к вашему сайту.

Что можно настроить для хостинга?

  • Укажите, какие файлы в вашем локальном каталоге проекта вы хотите развернуть на Firebase Hosting. Научиться.

  • Обслуживайте персонализированную страницу 404/Not Found. Научиться.

  • Настройте redirects для страниц, которые вы переместили или удалили. Научиться.

  • Настройте rewrites для любой из этих целей:

    • Показывать один и тот же контент для нескольких URL-адресов. Научиться.

    • Выполните функцию или получите доступ к контейнеру Cloud Run с URL-адреса хостинга. Узнайте, как: функция или контейнер .

    • Создайте динамическую ссылку личного домена. Научиться.

  • Добавьте headers , чтобы передать дополнительную информацию о запросе или ответе, например о том, как браузеры должны обрабатывать страницу и ее содержимое (аутентификация, кэширование, кодирование и т. д.). Научиться.

  • Настройте перезапись интернационализации (i18n) для обслуживания определенного контента в зависимости от языковых предпочтений пользователя и/или страны. Узнайте, как (другая страница).

Где вы определяете конфигурацию вашего хостинга?

Вы определяете конфигурацию хостинга Firebase в файле firebase.json . Firebase автоматически создает файл firebase.json в корне каталога вашего проекта, когда вы запускаете команду firebase init .

Вы можете найти полный пример конфигурации firebase.json (охватывающий только Firebase Hosting) внизу этой страницы. Обратите внимание, что файл firebase.json также может содержать конфигурации для других служб Firebase .

Вы можете проверить развернутое содержимое firebase.json с помощью Hosting REST API .

Приоритет ответов хостинга

Различные параметры конфигурации Firebase Hosting, описанные на этой странице, иногда могут пересекаться. В случае конфликта Hosting определяет свой ответ, используя следующий порядок приоритета:

  1. Зарезервированные пространства имен, начинающиеся с сегмента пути /__/*
  2. Настроенные редиректы
  3. Статическое содержимое с точным соответствием
  4. Настроенные перезаписи
  5. Пользовательская страница 404
  6. Страница 404 по умолчанию

Если вы используете перезапись i18n , порядок приоритетов обработки точного совпадения и ошибки 404 расширяется в соответствии с вашим «содержимым i18n».

Укажите, какие файлы нужно развернуть

Атрибуты по умолчанию — public и ignore — включенные в файл firebase.json по умолчанию определяют, какие файлы в каталоге вашего проекта должны быть развернуты в вашем проекте Firebase.

Конфигурация hosting по умолчанию в файле firebase.json выглядит так:

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

публичный

Необходимый
Атрибут public указывает, какой каталог следует развернуть на Firebase Hosting. Значением по умолчанию является каталог с именем public , но вы можете указать любой путь к каталогу, если он существует в каталоге вашего проекта.

Ниже приведено заданное по умолчанию имя каталога для развертывания:

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

  // ...
}

Вы можете изменить значение по умолчанию на каталог, который вы хотите развернуть:

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

  // ...
}

игнорировать

Необязательный
Атрибут ignore указывает файлы, которые следует игнорировать при развертывании. Он может принимать globs так же, как Git обрабатывает .gitignore .

Ниже приведены значения по умолчанию для игнорируемых файлов:

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

Firebase Hosting отобразит содержимое этой пользовательской страницы 404.html , если браузер выдаст ошибку 404 Not Found в вашем домене или субдомене.

Настроить перенаправления

Необязательный
Используйте перенаправление URL-адресов, чтобы предотвратить неработающие ссылки, если вы переместили страницу, или сократить URL-адреса. Например, вы можете перенаправить браузер с example.com/team на example.com/about.html .

Укажите перенаправления URL-адресов, создав атрибут redirects , который содержит массив объектов (называемых «правилами перенаправления»). В каждом правиле укажите шаблон URL-адреса, который, если он соответствует пути URL-адреса запроса, инициирует хостинг для ответа с перенаправлением на указанный целевой 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
  } ]
}

Атрибут redirects содержит массив правил перенаправления, где каждое правило должно включать поля из таблицы ниже.

Firebase Hosting сравнивает source или значение regex со всеми путями URL-адресов в начале каждого запроса (до того, как браузер определит, существует ли файл или папка по этому пути). Если совпадение найдено, исходный сервер Firebase Hosting отправляет ответ перенаправления HTTPS, сообщающий браузеру о необходимости сделать новый запрос по destination URL-адресу.

Поле Описание
redirects
source (рекомендуется)
или regex

Шаблон URL-адреса, который при сопоставлении с исходным URL-адресом запроса инициирует хостинг для применения перенаправления.

destination

Статический URL-адрес, по которому браузер должен сделать новый запрос.

Этот URL-адрес может быть относительным или абсолютным путем.

type

Код ответа HTTPS

  • Используйте тип 301 для «Перемещено навсегда».
  • Используйте тип 302 для «Найдено» (временное перенаправление)

Захват сегментов URL для перенаправления

Необязательный
Иногда вам может потребоваться захватить определенные сегменты шаблона URL-адреса правила перенаправления ( source или значение regex ), а затем повторно использовать эти сегменты в пути destination правила.

Настроить перезапись

Необязательный
Используйте перезапись, чтобы отобразить один и тот же контент для нескольких URL-адресов. Перезаписи особенно полезны при сопоставлении с шаблоном, поскольку вы можете принять любой URL-адрес, соответствующий шаблону, и позволить коду на стороне клиента решить, что отображать.

Вы также можете использовать перезаписи для поддержки приложений, использующих pushState HTML5 для навигации. Когда браузер пытается открыть путь URL-адреса, который соответствует указанному шаблону URL-адреса source или regex , вместо этого браузеру будет предоставлено содержимое файла по destination URL-адресу.

Укажите перезапись URL-адресов, создав атрибут rewrites , который содержит массив объектов (называемых «правилами перезаписи»). В каждом правиле укажите шаблон URL-адреса, который, если он соответствует пути URL-адреса запроса, инициирует хостинг для ответа, как если бы службе был предоставлен указанный целевой URL-адрес.

Вот базовая структура атрибута rewrites . В этом примере используется index.html для запросов к файлам или каталогам, которые не существуют.

"hosting": {
  // ...

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

Атрибут rewrites содержит массив правил перезаписи, где каждое правило должно включать поля из таблицы ниже.

Firebase Hosting применяет правило перезаписи только в том случае, если файл или каталог не существует по пути URL-адреса, который соответствует указанному шаблону URL-адреса source или regex . Когда запрос запускает правило перезаписи, браузер возвращает фактическое содержимое указанного destination файла вместо перенаправления HTTP.

Поле Описание
rewrites
source (рекомендуется)
или regex

Шаблон URL-адреса, который при совпадении с первоначальным URL-адресом запроса инициирует хостинг для применения перезаписи.

destination

Локальный файл, который должен существовать

Этот URL-адрес может быть относительным или абсолютным путем.

Прямые запросы к функции

Вы можете использовать rewrites для обслуживания функции с URL-адреса хостинга Firebase. Следующий пример представляет собой выдержку из обслуживания динамического контента с помощью 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)
    "pinTag": true           // 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 для доступа к контейнеру Cloud Run с URL-адреса хостинга Firebase. Следующий пример представляет собой выдержку из обслуживания динамического контента с помощью 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 требуется следующее:

Поле Описание
appAssociation

Должен быть установлен на AUTO

  • Если вы не включили этот атрибут в свою конфигурацию, по умолчанию для appAssociation установлено значение AUTO .
  • Установив для этого атрибута значение AUTO , Hosting может динамически генерировать файлы assetlinks.json и apple-app-site-association по запросу.
rewrites
source

Путь, который вы хотите использовать для динамических ссылок

В отличие от правил, которые переписывают пути к URL-адресам, правила перезаписи для динамических ссылок не могут содержать регулярные выражения.

dynamicLinks Должно быть установлено значение true

Настроить заголовки

Необязательный
Заголовки позволяют клиенту и серверу передавать дополнительную информацию вместе с запросом или ответом. Некоторые наборы заголовков могут влиять на то, как браузер обрабатывает страницу и ее содержимое, включая управление доступом, аутентификацию, кэширование и кодирование.

Укажите настраиваемые заголовки ответов для конкретных файлов, создав атрибут 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": "*"
    } ]
  } ]
}

Атрибут headers содержит массив определений, где каждое определение должно включать поля из таблицы ниже.

Поле Описание
headers
source (рекомендуется)
или regex

Шаблон URL-адреса, который при сопоставлении с исходным URL-адресом запроса инициирует хостинг для применения пользовательского заголовка.

Чтобы создать заголовок, соответствующий вашей пользовательской странице 404 , используйте 404.html в качестве source или значения regex .

массив (под) headers

Пользовательские заголовки, которые Hosting применяет к пути запроса

Каждый подзаголовок должен включать пару key - value (см. следующие две строки).

key Название шапки, например Cache-Control
value Значение для заголовка, например max-age=7200

Вы можете узнать больше о Cache-Control в разделе Хостинг, в котором описывается обслуживание динамического контента и размещение микросервисов. Вы также можете узнать больше о заголовках CORS .

Управление расширениями .html

Необязательный
Атрибут cleanUrls позволяет вам контролировать, должны ли URL-адреса включать расширение .html .

Если задано true , Hosting автоматически удаляет расширение .html из URL-адресов загружаемых файлов. Если в запрос добавляется расширение .html , Hosting выполняет перенаправление 301 на тот же путь, но удаляет расширение .html .

Вот как можно контролировать включение .html в URL-адреса, включив атрибут cleanUrls :

"hosting": {
  // ...

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

Управлять косой чертой в конце

Необязательный
Атрибут trailingSlash позволяет вам контролировать, должны ли URL-адреса статического контента включать косую черту в конце.

  • При значении true хостинг перенаправляет URL-адреса, добавляя косую черту в конце.
  • При значении false Хостинг перенаправляет URL-адреса, чтобы удалить завершающую косую черту.
  • Если не указано иное, Hosting использует косую черту только для индексных файлов каталогов (например, about/index.html ).

Вот как управлять косой чертой в конце, добавив атрибут trailingSlash :

"hosting": {
  // ...

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

Атрибут trailingSlash не влияет на перезапись динамического контента, обслуживаемого Cloud Functions или Cloud Run.

Сопоставление шаблона глобуса

Параметры конфигурации Firebase Hosting широко используют нотацию сопоставления шаблонов glob с extglob, подобно тому, как Git обрабатывает правила gitignore , а Bower обрабатывает правила ignore . Эта вики-страница является более подробным справочником, но ниже приведены пояснения к примерам, используемым на этой странице:

  • firebase.json — соответствует только файлу firebase.json в корне public каталога.

  • ** — Соответствует любому файлу или папке в произвольном подкаталоге.

  • * — Соответствует только файлам и папкам в корне public каталога.

  • **/.* — соответствует любому файлу, начинающемуся с . (обычно скрытые файлы, например, в папке .git ) в произвольном подкаталоге

  • **/node_modules/** — Соответствует любому файлу или папке в произвольном подкаталоге папки node_modules , которая сама может находиться в произвольном подкаталоге public каталога.

  • **/*.@(jpg|jpeg|gif|png) — соответствует любому файлу в произвольном подкаталоге, который заканчивается точно одним из следующих: .jpg , .jpeg , .gif или .png

Пример полной конфигурации хостинга

Ниже приведен полный пример конфигурации firebase.json для Firebase Hosting. Обратите внимание, что файл 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",

  }
}