Catch up on everything announced at Firebase Summit, and learn how Firebase can help you accelerate app development and run your app with confidence. Learn More

Configurar o comportamento de hospedagem

Mantenha tudo organizado com as coleções Salve e categorize o conteúdo com base nas suas preferências.

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 no diretório do projeto local você deseja implantar no Firebase Hosting. Aprenda como.

  • Exiba uma página personalizada 404/Not Found. 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.

    • Exiba uma função ou acesse um contêiner do Cloud Run a partir de um URL de hospedagem. Saiba 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, armazenamento em cache, codificação etc.). Aprenda como.

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

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

Você define a configuração do Firebase Hosting no 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 do Hosting .

Ordem de prioridade das respostas do Hosting

As diferentes opções de configuração do Firebase Hosting descritas nesta página às vezes podem se sobrepor. Se houver um conflito, o 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 404 padrão

Se você estiver usando reescritas de i18n , a ordem de prioridade de manipulação de correspondência exata e 404 será expandida no escopo para acomodar seu "conteúdo de 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 do Firebase.

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

"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 projeto.

Veja a seguir o nome especificado padrão 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
  ]
}

Personalizar uma página 404/Not Found

Opcional
Você pode exibir um erro personalizado 404 Not Found 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 404 Not Found personalizado ao arquivo.

O Firebase Hosting exibirá o conteúdo desta 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ê tiver movido 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 (chamadas "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 um array 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

Um URL estático 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)

Capturar 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 (valor de source ou regex ) e, em seguida, reutilizar esses segmentos no caminho de destination da regra.

Configurar regravações

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

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

Especifique regravações de URL criando um atributo de rewrites que contém uma matriz de objetos (chamadas "regras de regravação"). 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 de 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 uma matriz de regras de reescrita, onde cada regra deve incluir os campos da tabela abaixo.

O Firebase Hosting só aplica uma regra de reescrita 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 reescrita, 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 regravação

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 veicular uma função de um URL do Firebase Hosting. O exemplo a seguir é um trecho da veiculaçã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 Hosting, 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 veiculaçã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 o Hosting, 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 o Hosting 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 os prefixos de caminho de domínio personalizado 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 será 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 trata a página e seu conteúdo, incluindo controle de acesso, autenticação, armazenamento em cache e codificação.

Especifique cabeçalhos de resposta personalizados e específicos de 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 de solicitação, acione o Hosting para aplicar os cabeçalhos de resposta personalizados especificados.

Aqui está a estrutura básica para um atributo de 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 que corresponda à sua página 404 personalizada , use 404.html como seu valor de source ou regex .

array de (sub) headers

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

Cada sub-cabeç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 saber mais sobre Cache-Control na seção Hospedagem que descreve a veiculação de conteúdo dinâmico e microsserviços de hospedagem. Você também pode aprender mais sobre cabeçalhos CORS .

Controlar extensões .html

Opcional
O atributo cleanUrls permite controlar se os URLs devem ou não incluir a extensão .html .

Quando true , o Hosting descarta automaticamente a extensão .html dos URLs dos arquivos carregados. Se uma extensão .html for adicionada na solicitação, o Hosting executa 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 controlar se os URLs de conteúdo estático devem ou não incluir barras finais.

  • Quando true , o Hosting redireciona os URLs para adicionar uma barra à direita.
  • Quando false , o Hosting redireciona os 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 finais adicionando um atributo trailingSlash :

"hosting": {
  // ...

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

O atributo trailingSlash não afeta a regravação de conteúdo dinâmico veiculado pelo Cloud Functions ou Cloud Run.

Correspondência de padrões globais

As opções de configuração do Firebase Hosting fazem uso extensivo da notação de correspondência de padrões glob com extglob, semelhante à forma como o Git lida com as regras gitignore e o Bower 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",

  }
}