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

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

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

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

  • Создайте персонализированную страницу 404/Не найдено. Научиться.

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

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

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

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

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

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

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

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

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

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

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

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

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

  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. Значением по умолчанию является каталог с именем 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/Не найдено

Необязательный
Вы можете выдавать пользовательскую ошибку 404 Not Found , когда пользователь пытается получить доступ к несуществующей странице.

Создайте новый файл в public каталоге вашего проекта, назовите его 404.html , затем добавьте в него собственный контент 404 Not Found .

Хостинг Firebase отобразит содержимое этой пользовательской страницы 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 сравнивает значение source или regex со всеми URL-путями в начале каждого запроса (прежде чем браузер определит, существует ли файл или папка по этому пути). Если совпадение найдено, исходный сервер хостинга Firebase отправляет ответ на перенаправление HTTPS, сообщая браузеру выполнить новый запрос по destination URL-адресу.

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

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

destination

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

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

type

Код ответа HTTPS

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

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

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

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

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

Вы также можете использовать перезаписи для поддержки приложений, использующих HTML5 pushState для навигации. Когда браузер пытается открыть путь 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 применяет правило перезаписи только в том случае, если файл или каталог не существует по 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": {
      "functionId": "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

При перенаправлении запросов к функциям с помощью хостинга поддерживаются методы 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 вместе с хостингом, используя следующие регионы:

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

Перезапись в Cloud Run с хостинга поддерживается в следующих регионах:

  • 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

Вы можете использовать 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 , хостинг может динамически генерировать файлы assetlinks.json и apple-app-site-association по запросу.
rewrites
source

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

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

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

Настройка заголовков

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

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

Вот базовая структура атрибута 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

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

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

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

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

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

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

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

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

"hosting": {
  // ...

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

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

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

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

Вот как можно управлять завершающими косыми чертами, добавляя атрибут trailingSlash :

"hosting": {
  // ...

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

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

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

В параметрах конфигурации хостинга Firebase широко используется нотация соответствия шаблону 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. Обратите внимание, что файл 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",

  }
}