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

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

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

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

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

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

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

  • Показывать один и тот же контент для нескольких URL-адресов. Узнайте, как это сделать.

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

  • Создайте личный домен Dynamic Link . Узнайте, как это сделать.

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

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

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

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

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

Вы можете проверить развернутое содержимое firebase.json с помощью API REST 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
  } ]
}

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

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

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

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

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

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

Настройка перезаписи

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

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

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

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

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

Вы можете использовать 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

Создание Dynamic Links личного домена

Вы можете использовать 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 требуется следующее:

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

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

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

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

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

Вы можете узнать больше о 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",

  }
}