Ir para o console

Configurar o comportamento de hosting

Com o Firebase Hosting, é possível configurar o comportamento de hospedagem personalizado, incluindo páginas de erro, redirecionamentos, substituições e cabeçalhos personalizados. Você também pode especificar quais arquivos implantar do diretório do seu projeto para o seu projeto do Firebase.

Defina a configuração do Firebase Hosting no arquivo firebase.json.

Encontre o arquivo firebase.json na raiz do diretório do projeto. O Firebase cria automaticamente o arquivo firebase.json quando você executa o comando firebase init.

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

É possível verificar o conteú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 podem, às vezes, se sobrepor. Se houver um conflito, o Hosting determinará 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. substituições configuradas
  5. página 404 personalizada
  6. página 404 padrão

Especificar os arquivos a serem implantados

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

A configuração hosting padrão em um arquivo firebase.json tem a seguinte aparência:

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

public

Obrigatório
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 ele exista no diretório do projeto.

Veja abaixo o nome especificado padrão do diretório a ser implantado:

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

  // ...
}

É possível alterar o valor padrão para o diretório que você quer implantar:

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

  // ...
}

ignore

Opcional
O atributo ignore especifica os arquivos a serem ignorados na implantação. Ele pode usar o padrão glob da mesma maneira que o Git manipula .gitignore.

Veja abaixo os valores padrão dos arquivos a serem ignorados:

"hosting": {
  // ...

  "ignore": [
    "firebase.json",  // the Firebase configuration file (this file)
    "**/.*",  // 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/não encontrada

Opcional
Você pode exibir um erro 404 Not Found personalizado quando um usuário tentar 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 o conteúdo 404 Not Found personalizado ao arquivo.

O Firebase Hosting exibirá o conteúdo dessa página 404.html personalizada se um navegador acionar um erro 404 Not Found no 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 incluindo um atributo redirects em hosting no arquivo firebase.json. Exemplo:

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

O atributo redirects contém uma matriz de regras de redirecionamento, em que cada regra precisa incluir:

  • Um source especificando um padrão glob

  • Um destination, que é um URL estático que pode ser um caminho relativo ou absoluto

  • Um type especificando o código de resposta HTTP

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

Por fim, o valor type especifica o código de resposta HTTP específico exibido e pode ser 301 para "Movido permanentemente" ou 302 para "Encontrado" (Redirecionamento temporário).

Capturar segmentos de URL para redirecionamentos

Opcional
Às vezes, pode ser necessário capturar segmentos específicos de um URL de source de redirecionamento e, em seguida, reutilizar esses segmentos no URL de destination de redirecionamento.

É possível capturar esses segmentos incluindo um prefixo : para identificar o segmento. Se você também precisar capturar o caminho de URL restante após o segmento, inclua um * imediatamente após o segmento. Exemplo:

"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 caputured by the "source" value
    "type": 301
  } ]
}

Configurar substituições

Opcional
Use uma substituição para mostrar o mesmo conteúdo para vários URLs. As substituições são muito úteis com correspondência de padrões, já que você pode aceitar qualquer URL que corresponda ao padrão e deixar que o código do cliente decida o que será exibido.

As substituições também podem ser usadas para dar suporte a apps que usam HTML5 pushState para navegação. Quando um navegador tenta abrir um URL de source especificado, ele recebe o conteúdo do arquivo no URL de destination.

Especifique as substituições de URL incluindo um atributo rewrites em hosting no arquivo firebase.json. Exemplo:

"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"
  }, {
    // Excludes specified pathways from rewrites
    "source": "!/@(js|css)/**",
    "destination": "/index.html"
  } ]
}

O atributo rewrites contém uma matriz de regras de substituições, em que cada regra precisa incluir:

  • Um source especificando um padrão glob

  • Um destination, que é um arquivo local que precisa existir

O Firebase Hosting aplicará uma regra de substituição apenas se um arquivo ou diretório não existir na source especificada. Quando uma regra é acionada, o navegador retorna o conteúdo real do arquivo de destination especificado em vez de um redirecionamento de HTTP.

Solicitações diretas para uma função

Você pode usar rewrites para exibir 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 no seu site do Hosting com o objetivo de executar a função bigben:

"hosting": {
  // ...

  // Add the "rewrites" attribute within "hosting"
  "rewrites": [ {
    "source": "/bigben",
    "function": "bigben"
  } ]
}

Após adicionar a regra de substituição e implantá-la para o Firebase (usando o comando firebase deploy), sua função pode ser acessada por meio dos URLs a seguir:

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

  • Todos os domínios personalizados conectados: custom-domain/bigben

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 do Hosting para acionar a inicialização e a execução de uma instância de contêiner helloworld:

"hosting": {
 // ...

 // Add the "rewrites" attribute within "hosting"
 "rewrites": [ {
   "source": "/helloworld",
   "run": {
     "serviceId": "helloworld",  // "service name" (from when you <a href="#deploy">deployed the container image)</a>
     "region": "us-central1"     // optional (if omitted, default is us-central1)
   }
 } ]
}

Após adicionar a regra de substituição e implantá-la para o Firebase (usando o comando firebase deploy), sua imagem de contêiner pode ser acessada por meio dos URLs a seguir:

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

  • Todos os domínios personalizados conectados: custom-domain/helloworld

É possível usar rewrites para criar Dynamic Links de domínio personalizado. Visite a documentação de Dynamic Links para receber informações detalhadas sobre a configuração de um domínio personalizado para Dynamic Links.

Por exemplo:

  • Use seu domínio apenas para Dynamic Links:

    "hosting": {
      // ...
    
      "appAssociation": "AUTO",  // required for Dynamic Links (default is AUTO if not specified)
    
      // Add the "rewrites" attribute within "hosting"
      "rewrites": [ {
        "source": "/**",  // Dynamic Links start with "https://<your-domain>/"
        "dynamicLinks": true
      } ]
    }
    
  • Especifique os prefixos de caminho que você quer usar para Dynamic Links:

    "hosting": {
      // ...
    
      "appAssociation": "AUTO",  // required for Dynamic Links (default is AUTO if not specified)
    
      // Add the "rewrites" attribute within "hosting"
      "rewrites": [ {
        "source": "/promos/**",  // Dynamic Links can start with "https://<your-domain>/promos/"
        "dynamicLinks": true
      }, {
        "source": "/links/share/**",  // Dynamic Links can start with "https://<your-domain>/links/share/"
        "dynamicLinks": true
      } ]
    }
    

Configurar o Dynamic Links no arquivo firebase.json requer:

  • Um atributo appAssociation definido como AUTO.

    • O padrão para appAssociation será AUTO se você não incluir o atributo na configuração.
    • Com esse atributo definido como AUTO, o Hosting gera, dinamicamente, os arquivos assetlinks.json e apple-app-site-association quando eles são solicitados.
  • Um atributo rewrites para Dynamic Links que contém uma matriz de regras de substituição, em que cada regra precisa incluir:

    • Uma source especificando um caminho que você quer usar para Dynamic Links

      • Ao contrário das regras que substituem caminhos por URLs, as regras de substituição do Dynamic Links não podem conter expressões regulares.
    • Um atributo dynamicLinks 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 uma 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, armazenamento em cache e codificação.

Especifique cabeçalhos de resposta personalizados específicos do arquivo incluindo um atributo headers em hosting no arquivo firebase.json. Exemplo:

"hosting": {
  // ...

  // Add the "headers" attribute within "hosting"
  "headers": [ {
    // Specifies 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"
    } ]
  }, {
    // Sets the cache header for 404 pages to cache for 5 minutes
    "source": "404.html",
    "headers": [ {
      "key": "Cache-Control",
      "value": "max-age=300"
    } ]
  } ]
}

O atributo headers contém uma matriz de definições, em que cada definição precisa incluir estes itens:

  • Um valor de source que o Hosting corresponde ao caminho da solicitação original, independentemente de quaisquer regras de substituição.

  • Uma matriz de (sub-)headers aplicada pelo Hosting ao caminho da solicitação. Cada matriz de subcabeçalho precisa incluir um key e um value especificados.

Saiba mais sobre Cache-Control na seção "Hosting" que descreve a exibição de conteúdo dinâmico e hospedagem de microsserviços.

É possível também saber mais sobre os cabeçalhos do CORS.

Controlar extensões .html

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

Quando true, o Hosting automaticamente descarta a extensão .html dos URLs de arquivos enviados. Se uma extensão .html for adicionada à solicitação, o Hosting executará um redirecionamento 301 para o mesmo caminho, mas eliminará a extensão .html.

Especifique a inclusão de extensões .html ao incluir um atributo cleanUrls em hosting no arquivo firebase.json. Exemplo:

"hosting": {
  // ...

  // Add the "cleanUrls" attribute within "hosting"
  "cleanUrls": true
}

Controlar barras finais

Opcional
O atributo trailingSlash permite controlar se os URLs precisam ou não incluir barras finais.

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

Especifique a inclusão de barras finais incluindo um atributo trailingSlash em hosting no arquivo firebase.json. Exemplo:

"hosting": {
  // ...

  // Add the "trailingSlash" attribute within "hosting"
  "trailingSlash": false
}

Correspondência de padrões glob

As opções de configuração do Firebase Hosting usam muito a notação de correspondência de padrão de glob com extglob, semelhante a como o Git usa as regras gitignore e o Bower usa as regras ignore. Esta página da wiki é uma referência mais detalhada, mas as seguintes são explicações dos 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 termina exatamente com uma das opções a seguir: .jpg, .jpeg, .gif ou .png

Exemplo de configuração completa do Hosting

Veja a seguir um exemplo completo de configuração de firebase.json para o Firebase Hosting. 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",

  }
}