获取我们在 Firebase 峰会上发布的所有信息,了解 Firebase 可如何帮助您加快应用开发速度并满怀信心地运行应用。了解详情

Configurar o comportamento de hospedagem

Com o Firebase Hosting, você pode configurar o comportamento de hospedagem personalizado para solicitações ao seu site.

O que você pode configurar para hospedagem?

  • Especifique quais arquivos em seu diretório de projeto local você deseja implantar no Firebase Hosting. Aprenda como.

  • Exiba uma página personalizada 404/Não encontrado. Aprenda como.

  • Configure redirects para páginas que você moveu ou excluiu. Aprenda como.

  • Configure rewrites para qualquer um destes propósitos:

    • Mostre o mesmo conteúdo para vários URLs. Aprenda como.

    • Atenda a uma função ou acesse um contêiner do Cloud Run a partir de um URL de hospedagem. Aprenda como: função ou contêiner .

    • Crie um link dinâmico de domínio personalizado. Aprenda como.

  • Adicione headers para transmitir informações adicionais sobre uma solicitação ou resposta, como como os navegadores devem lidar com a página e seu conteúdo (autenticação, cache, codificação, etc.). Aprenda como.

  • Configure regravações de internacionalização (i18n) para fornecer conteúdo específico com base na preferência de idioma e/ou país do usuário. Saiba como (página diferente).

Onde você define sua configuração de hospedagem?

Você define a configuração do Firebase Hosting em seu arquivo firebase.json . O Firebase cria automaticamente o arquivo firebase.json na raiz do diretório do projeto quando você executa o comando firebase init .

Você pode encontrar um exemplo completo de configuração do firebase.json (abrangendo apenas o Firebase Hosting) na parte inferior desta página. Observe que um arquivo firebase.json também pode conter configurações para outros serviços do Firebase .

Você pode verificar o conteúdo do firebase.json implantado usando a API REST de hospedagem .

Ordem de prioridade das respostas de hospedagem

Às vezes, as diferentes opções de configuração do Firebase Hosting descritas nesta página podem se sobrepor. Se houver um conflito, a Hosting determina sua resposta usando a seguinte ordem de prioridade:

  1. Namespaces reservados que começam com um segmento de caminho /__/*
  2. Redirecionamentos configurados
  3. Conteúdo estático de correspondência exata
  4. Reescritas configuradas
  5. Página 404 personalizada
  6. Página padrão 404

Se você estiver usando reescritas i18n , a correspondência exata e a ordem de prioridade de tratamento 404 serão expandidas no escopo para acomodar seu "conteúdo i18n".

Especifique quais arquivos implantar

Os atributos padrão — public e ignore — incluídos no arquivo firebase.json padrão definem quais arquivos no diretório do projeto devem ser implantados no projeto Firebase.

A configuração de hosting padrão em um arquivo firebase.json é semelhante a esta:

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

público

Requeridos
O atributo public especifica qual diretório implantar no Firebase Hosting. O valor padrão é um diretório chamado public , mas você pode especificar o caminho de qualquer diretório, desde que exista no diretório do seu projeto.

A seguir está o nome padrão especificado do diretório a ser implantado:

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

  // ...
}

Você pode alterar o valor padrão para o diretório que deseja implantar:

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

  // ...
}

ignorar

Opcional
O atributo ignore especifica os arquivos a serem ignorados na implantação. Ele pode receber globs da mesma forma que o Git lida com .gitignore .

A seguir estão os valores padrão para os arquivos a serem ignorados:

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

Personalize uma página 404/Não encontrado

Opcional
Você pode exibir um erro 404 Not Found personalizado quando um usuário tenta acessar uma página que não existe.

Crie um novo arquivo no diretório public do seu projeto, nomeie-o como 404.html e adicione seu conteúdo personalizado 404 Not Found ao arquivo.

O Firebase Hosting exibirá o conteúdo dessa página 404.html personalizada se um navegador acionar um erro 404 Not Found em seu domínio ou subdomínio.

Configurar redirecionamentos

Opcional
Use um redirecionamento de URL para evitar links quebrados se você moveu uma página ou para encurtar URLs. Por exemplo, você pode redirecionar um navegador de example.com/team para example.com/about.html .

Especifique redirecionamentos de URL criando um atributo de redirects que contém uma matriz de objetos (chamados de "regras de redirecionamento"). Em cada regra, especifique um padrão de URL que, se corresponder ao caminho do URL de solicitação, acione o Hosting para responder com um redirecionamento para o URL de destino especificado.

Aqui está a estrutura básica para um atributo de redirects . Este exemplo redireciona solicitações para /foo fazendo uma nova solicitação para /bar .

"hosting": {
  // ...

  // Returns a permanent redirect to "/bar" for requests to "/foo" (but not "/foo/**")
  "redirects": [ {
    "source": "/foo",
    "destination": "/bar",
    "type": 301
  } ]
}

O atributo redirects contém uma matriz de regras de redirecionamento, onde cada regra deve incluir os campos da tabela abaixo.

O Firebase Hosting compara o valor de source ou regex com todos os caminhos de URL no início de cada solicitação (antes que o navegador determine se existe um arquivo ou pasta nesse caminho). Se uma correspondência for encontrada, o servidor de origem do Firebase Hosting enviará uma resposta de redirecionamento HTTPS informando ao navegador para fazer uma nova solicitação no URL de destination .

Campo Descrição
redirects
source (recomendado)
ou regex

Um padrão de URL que, se corresponder ao URL de solicitação inicial, aciona o Hosting para aplicar o redirecionamento

destination

Uma URL estática onde o navegador deve fazer uma nova solicitação

Essa URL pode ser um caminho relativo ou absoluto.

type

O código de resposta HTTPS

  • Use um tipo de 301 para 'Movido Permanentemente'
  • Use um tipo de 302 para 'Encontrado' (redirecionamento temporário)

Capture segmentos de URL para redirecionamentos

Opcional
Às vezes, pode ser necessário capturar segmentos específicos do padrão de URL de uma regra de redirecionamento ( source ou valor regex ) e reutilizar esses segmentos no caminho de destination da regra.

Configurar reescritas

Opcional
Use uma reescrita para mostrar o mesmo conteúdo para vários URLs. As reescritas são particularmente úteis com a correspondência de padrões, pois você pode aceitar qualquer URL que corresponda ao padrão e deixar que o código do lado do cliente decida o que exibir.

Você também pode usar reescritas para oferecer suporte a aplicativos que usam HTML5 pushState para navegação. Quando um navegador tenta abrir um caminho de URL que corresponda à source especificada ou ao padrão de URL regex , o navegador receberá o conteúdo do arquivo no URL de destination .

Especifique reescritas de URL criando um atributo rewrites que contém uma matriz de objetos (chamadas "regras de reescrita"). Em cada regra, especifique um padrão de URL que, se corresponder ao caminho do URL de solicitação, acione o Hosting para responder como se o serviço tivesse recebido o URL de destino especificado.

Aqui está a estrutura básica para um atributo rewrites . Este exemplo serve index.html para solicitações de arquivos ou diretórios que não existem.

"hosting": {
  // ...

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

O atributo rewrites contém um array de regras de rewrite, onde cada regra deve incluir os campos na tabela abaixo.

O Firebase Hosting só aplica uma regra de regravação se um arquivo ou diretório não existir em um caminho de URL que corresponda à source especificada ou ao padrão de URL regex . Quando uma solicitação aciona uma regra de regravação, o navegador retorna o conteúdo real do arquivo de destination especificado em vez de um redirecionamento HTTP.

Campo Descrição
rewrites
source (recomendado)
ou regex

Um padrão de URL que, se corresponder ao URL de solicitação inicial, aciona o Hosting para aplicar a reescrita

destination

Um arquivo local que deve existir

Essa URL pode ser um caminho relativo ou absoluto.

Solicitações diretas a uma função

Você pode usar rewrites para atender a uma função de um URL do Firebase Hosting. O exemplo a seguir é um trecho da exibição de conteúdo dinâmico usando o Cloud Functions .

Por exemplo, para direcionar todas as solicitações da página /bigben em seu site de hospedagem para executar a função 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)
  } ]
}

Depois de adicionar esta regra de reescrita e implantar no Firebase (usando firebase deploy ), sua função pode ser acessada por meio dos seguintes URLs:

  • Seus subdomínios do Firebase:
    PROJECT_ID .web.app/bigben e PROJECT_ID .firebaseapp.com/bigben

  • Quaisquer domínios personalizados conectados:
    CUSTOM_DOMAIN /bigben

Ao redirecionar solicitações para funções com hospedagem, os métodos de solicitação HTTP suportados são GET , POST , HEAD , PUT , DELETE , PATCH e OPTIONS . Outros métodos como REPORT ou PROFIND não são suportados.

Solicitações diretas para um contêiner do Cloud Run

Você pode usar rewrites para acessar um contêiner do Cloud Run a partir de um URL do Firebase Hosting. O exemplo a seguir é um trecho da exibição de conteúdo dinâmico usando o Cloud Run .

Por exemplo, para direcionar todas as solicitações da página /helloworld em seu site de hospedagem para acionar a inicialização e a execução de uma instância de contêiner 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)
   }
 } ]
}

Depois de adicionar esta regra de reescrita e implantar no Firebase (usando firebase deploy ), sua imagem de contêiner pode ser acessada por meio dos seguintes URLs:

  • Seus subdomínios do Firebase:
    PROJECT_ID .web.app/helloworld e PROJECT_ID .firebaseapp.com/helloworld

  • Quaisquer domínios personalizados conectados:
    CUSTOM_DOMAIN /helloworld

Ao redirecionar solicitações para contêineres do Cloud Run com hospedagem, os métodos de solicitação HTTP compatíveis são GET , POST , HEAD , PUT , DELETE , PATCH e OPTIONS . Outros métodos como REPORT ou PROFIND não são suportados.

Atualmente, você pode usar as reescritas do Cloud Run com hospedagem nas seguintes regiões:

  • 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

Você pode usar rewrites para criar links dinâmicos de domínio personalizado. Visite a documentação do Dynamic Links para obter informações detalhadas sobre como configurar um domínio personalizado para Dynamic Links .

  • Use seu domínio personalizado apenas para links dinâmicos

    "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
      } ]
    }
    
  • Especifique prefixos de caminho de domínio personalizados a serem usados ​​para links dinâmicos

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

A configuração de links dinâmicos em seu arquivo firebase.json requer o seguinte:

Campo Descrição
appAssociation

Deve ser definido como AUTO

  • Se você não incluir esse atributo em sua configuração, o padrão para appAssociation é AUTO .
  • Ao definir esse atributo como AUTO , o Hosting pode gerar dinamicamente os assetlinks.json e apple-app-site-association quando solicitados.
rewrites
source

Um caminho que você deseja usar para links dinâmicos

Ao contrário das regras que reescrevem caminhos para URLs, as regras de reescrita para links dinâmicos não podem conter expressões regulares.

dynamicLinks Deve ser definido como true

Configurar cabeçalhos

Opcional
Os cabeçalhos permitem que o cliente e o servidor passem informações adicionais junto com uma solicitação ou resposta. Alguns conjuntos de cabeçalhos podem afetar como o navegador lida com a página e seu conteúdo, incluindo controle de acesso, autenticação, cache e codificação.

Especifique cabeçalhos de resposta personalizados e específicos do arquivo criando um atributo headers que contém uma matriz de objetos de cabeçalho. Em cada objeto, especifique um padrão de URL que, se corresponder ao caminho do URL da solicitação, acione o Hosting para aplicar os cabeçalhos de resposta personalizados especificados.

Aqui está a estrutura básica de um atributo headers . Este exemplo aplica um cabeçalho CORS para todos os arquivos de fonte.

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

O atributo headers contém um array de definições, onde cada definição deve incluir os campos da tabela abaixo.

Campo Descrição
headers
source (recomendado)
ou regex

Um padrão de URL que, se corresponder ao URL de solicitação inicial, aciona o Hosting para aplicar o cabeçalho personalizado

Para criar um cabeçalho para corresponder à sua página 404 personalizada , use 404.html como source ou valor regex .

matriz de (sub-) headers

Os cabeçalhos personalizados que o Hosting aplica ao caminho da solicitação

Cada subcabeçalho deve incluir um par de key e value (veja as próximas duas linhas).

key O nome do cabeçalho, por exemplo Cache-Control
value O valor do cabeçalho, por exemplo max-age=7200

Você pode aprender mais sobre Cache-Control na seção Hospedagem que descreve a exibição de conteúdo dinâmico e a hospedagem de microsserviços. Você também pode aprender mais sobre cabeçalhos CORS .

Controlar extensões .html

Opcional
O atributo cleanUrls permite que você controle se os URLs devem ou não incluir a extensão .html .

Quando true , o Hosting remove automaticamente a extensão .html dos URLs dos arquivos carregados. Se uma extensão .html for adicionada na solicitação, o Hosting realiza um redirecionamento 301 para o mesmo caminho, mas elimina a extensão .html .

Veja como controlar a inclusão de .html em URLs incluindo um atributo cleanUrls :

"hosting": {
  // ...

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

Controlar barras à direita

Opcional
O atributo trailingSlash permite que você controle se os URLs de conteúdo estático devem ou não incluir barras à direita.

  • Quando true , o Hosting redireciona os URLs para adicionar uma barra à direita.
  • Quando false , o Hosting redireciona URLs para remover uma barra final.
  • Quando não especificado, o Hosting usa apenas barras à direita para arquivos de índice de diretório (por exemplo, about/index.html ).

Veja como controlar as barras à direita adicionando um atributo trailingSlash :

"hosting": {
  // ...

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

O atributo trailingSlash não afeta as regravações do conteúdo dinâmico fornecido pelo Cloud Functions ou Cloud Run.

Correspondência de padrão glob

As opções de configuração do Firebase Hosting fazem uso extensivo da notação de correspondência de padrão glob com extglob, semelhante a como o Git lida com as regras gitignore e o Bower lida com as regras ignore . Esta página wiki é uma referência mais detalhada, mas as seguintes são explicações de exemplos usados ​​nesta página:

  • firebase.json — Corresponde apenas ao arquivo firebase.json na raiz do diretório public

  • ** — Corresponde a qualquer arquivo ou pasta em um subdiretório arbitrário

  • * — Corresponde apenas a arquivos e pastas na raiz do diretório public

  • **/.* — Corresponde a qualquer arquivo que comece com . (geralmente arquivos ocultos, como na pasta .git ) em um subdiretório arbitrário

  • **/node_modules/** — Corresponde a qualquer arquivo ou pasta em um subdiretório arbitrário de uma pasta node_modules , que pode estar em um subdiretório arbitrário do diretório public

  • **/*.@(jpg|jpeg|gif|png) — Corresponde a qualquer arquivo em um subdiretório arbitrário que termine exatamente com um dos seguintes: .jpg , .jpeg , .gif ou .png

Exemplo de configuração de hospedagem completa

Veja a seguir um exemplo completo de configuração do firebase.json para o Firebase Hosting. Observe que um arquivo firebase.json também pode conter configurações para outros serviços do 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",

  }
}