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

С помощью 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
  } ]
}

"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-адрес, соответствующий шаблону, и позволить коду на стороне клиента решить, что отображать.

Вы также можете использовать перезаписи для поддержки приложений, использующих 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"
  } ]
}

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

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

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

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

  }
}