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

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

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

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

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

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

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

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

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

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

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

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

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

Приоритетный порядок ответов Hosting

Различные параметры конфигурации 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/Не найдено

Необязательный
Вы можете выдавать пользовательскую ошибку 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-адреса запроса, заставляет Hosting отвечать перенаправлением на указанный целевой 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-адресу первоначального запроса, заставляет Hosting применять перенаправление.

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-адреса запроса, заставляет Hosting отвечать так, как если бы службе был предоставлен указанный целевой 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-адресу первоначального запроса, заставляет Hosting применить перезапись.

destination

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

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

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

Вы можете использовать rewrites для обслуживания функции из URL-адреса Firebase Hosting . Следующий пример представляет собой отрывок из обслуживания динамического контента с помощью Cloud Functions .

Например, чтобы направить все запросы со страницы /bigben на вашем Hosting на выполнение функции 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

При перенаправлении запросов к функциям с помощью Hosting поддерживаются методы HTTP-запросов: GET , POST , HEAD , PUT , DELETE , PATCH и OPTIONS . Другие методы, такие как REPORT или PROFIND не поддерживаются.

Прямые запросы к контейнеру Cloud Run

Вы можете использовать rewrites для доступа к контейнеру Cloud Run по URL-адресу Firebase Hosting . Следующий пример представляет собой отрывок из обслуживания динамического контента с помощью Cloud Run .

Например, чтобы направить все запросы со страницы /helloworld на вашем Hosting сайте на запуск и запуск экземпляра контейнера 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 с Hosting поддерживаются методы HTTP-запросов: GET , POST , HEAD , PUT , DELETE , PATCH и OPTIONS . Другие методы, такие как REPORT или PROFIND не поддерживаются.

Для достижения наилучшей производительности разместите службу Cloud Run вместе с Hosting используя следующие регионы:

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

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

  • 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 для создания Dynamic Links личного домена. Посетите документацию Dynamic Links для получения подробной информации о настройке личного домена для Dynamic Links .

  • Используйте свой личный домен только для 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
      } ]
    }
  • Укажите префиксы путей к пользовательскому домену, которые будут использоваться для 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
      } ]
    }

Для настройки Dynamic Links в файле firebase.json требуется следующее:

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

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

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

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

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

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-адресу первоначального запроса, заставляет Hosting применять пользовательский заголовок.

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

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

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

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

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

Вы можете узнать больше о Cache-Control в разделе Hosting , где описывается обслуживание динамического контента и размещение микросервисов. Вы также можете узнать больше о заголовках 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 , Hosting перенаправляет URL-адреса, добавляя косую черту в конце.
  • Если false , Hosting перенаправляет URL-адреса, чтобы удалить косую черту в конце.
  • Если этот параметр не указан, Hosting использует только косую черту в конце для индексных файлов каталога (например, about/index.html ).

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

"hosting": {
  // ...

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

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

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

В параметрах конфигурации 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

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

Ниже приведен полный пример конфигурации 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",

  }
}