Configurar comportamiento de hospedaje

Con Firebase Hosting, puede configurar un comportamiento de alojamiento personalizado para las solicitudes a su sitio.

¿Qué puedes configurar para Hosting?

• Especifique qué archivos en su directorio de proyecto local desea implementar en Firebase Hosting. Aprender cómo.

• Sirve una página personalizada 404/No encontrado. Aprender cómo.

• Configure redirects para las páginas que ha movido o eliminado. Aprender cómo.

• Configure rewrites para cualquiera de estos propósitos:

  • Muestra el mismo contenido para varias URL. Aprender cómo.

  • Realice una función o acceda a un contenedor de Cloud Run desde una URL de hospedaje. Aprende cómo: función o contenedor .

  • Cree un enlace dinámico de dominio personalizado. Aprender cómo.

• Agregue headers para transmitir información adicional sobre una solicitud o una respuesta, por ejemplo, cómo los navegadores deben manejar la página y su contenido (autenticación, almacenamiento en caché, codificación, etc.). Aprender cómo.

• Configure las reescrituras de internacionalización (i18n) para ofrecer contenido específico según la preferencia de idioma o el país del usuario. Aprende cómo (página diferente).

¿Dónde defines tu configuración de Hosting?

Usted define su configuración de Firebase Hosting en su archivo firebase.json . Firebase crea automáticamente su archivo firebase.json en la raíz del directorio de su proyecto cuando ejecuta el comando firebase init .

Puede encontrar un ejemplo completo de configuración de firebase.json (que cubre solo Firebase Hosting) en la parte inferior de esta página. Tenga en cuenta que un archivo firebase.json también puede contener configuraciones para otros servicios de Firebase .

Puede comprobar el contenido de firebase.json implementado mediante la API REST de alojamiento .

Orden de prioridad de las respuestas de Hosting

Las diferentes opciones de configuración de Firebase Hosting que se describen en esta página a veces pueden superponerse. Si hay un conflicto, Hosting determina su respuesta utilizando el siguiente orden de prioridad:

1. Espacios de nombres reservados que comienzan con un segmento de ruta /__/*
2. Redirecciones configuradas
3. Contenido estático de coincidencia exacta
4. Reescrituras configuradas
5. Página 404 personalizada
6. Página 404 predeterminada

Si usa reescrituras de i18n , la coincidencia exacta y el orden de prioridad de manejo 404 se amplían en alcance para adaptarse a su "contenido de i18n".

Especificar qué archivos implementar

Los atributos predeterminados ( public e ignore ) incluidos en el archivo firebase.json predeterminado definen qué archivos en el directorio de su proyecto deben implementarse en su proyecto de Firebase.

La configuración de hosting predeterminada en un archivo firebase.json se ve así:

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

público

Requerido
El atributo public especifica qué directorio implementar en Firebase Hosting. El valor predeterminado es un directorio llamado public , pero puede especificar la ruta de cualquier directorio, siempre que exista en el directorio de su proyecto.

El siguiente es el nombre especificado predeterminado del directorio para implementar:

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

  // ...
}

Puede cambiar el valor predeterminado al directorio que desea implementar:

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

  // ...
}

pasar por alto

Opcional
El atributo ignore especifica los archivos que se ignorarán en la implementación. Puede tomar globs de la misma manera que Git maneja .gitignore .

Los siguientes son los valores predeterminados para que los archivos los ignoren:

"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 una página 404/No encontrado

Opcional
Puede mostrar un error 404 Not Found personalizado cuando un usuario intenta acceder a una página que no existe.

Cree un nuevo archivo en el directorio public de su proyecto, asígnele el nombre 404.html y luego agregue su contenido 404 Not Found personalizado al archivo.

Firebase Hosting mostrará el contenido de esta página 404.html personalizada si un navegador activa un error 404 Not Found en su dominio o subdominio.

Configurar redirecciones

Opcional
Utilice una redirección de URL para evitar enlaces rotos si ha movido una página o para acortar las URL. Por ejemplo, puede redirigir un navegador desde example.com/team a example.com/about.html .

Especifique los redireccionamientos de URL creando un atributo de redirects que contenga una matriz de objetos (llamados "reglas de redireccionamiento"). En cada regla, especifique un patrón de URL que, si coincide con la ruta de la URL de la solicitud, haga que Hosting responda con una redirección a la URL de destino especificada.

Esta es la estructura básica de un atributo de redirects . Este ejemplo redirige las solicitudes a /foo realizando una nueva solicitud a /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
  } ]
}

El atributo de redirects contiene una matriz de reglas de redireccionamiento, donde cada regla debe incluir los campos de la tabla a continuación.

Firebase Hosting compara el valor source o regex con todas las rutas de URL al comienzo de cada solicitud (antes de que el navegador determine si existe un archivo o una carpeta en esa ruta). Si se encuentra una coincidencia, el servidor de origen de Firebase Hosting envía una respuesta de redireccionamiento HTTPS que le indica al navegador que realice una nueva solicitud en la URL de destination .

Capture segmentos de URL para redireccionamientos

Opcional
A veces, es posible que deba capturar segmentos específicos del patrón de URL de una regla de redirección ( source o valor de regex ) y luego reutilizar estos segmentos en la ruta de destination de la regla.

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

Configurar reescrituras

Opcional
Utilice una reescritura para mostrar el mismo contenido para varias URL. Las reescrituras son particularmente útiles con la coincidencia de patrones, ya que puede aceptar cualquier URL que coincida con el patrón y dejar que el código del lado del cliente decida qué mostrar.

También puede usar reescrituras para admitir aplicaciones que usan HTML5 pushState para la navegación. Cuando un navegador intenta abrir una ruta de URL que coincida con el patrón de URL de source o regex especificado, el navegador recibirá el contenido del archivo en la URL de destination .

Especifique las reescrituras de URL creando un atributo de rewrites que contenga una matriz de objetos (llamadas "reglas de reescritura"). En cada regla, especifique un patrón de URL que, si coincide con la ruta de URL de la solicitud, haga que Hosting responda como si el servicio tuviera la URL de destino especificada.

Esta es la estructura básica de un atributo de rewrites . Este ejemplo sirve index.html para solicitudes a archivos o directorios que no existen.

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

El atributo de rewrites contiene una matriz de reglas de reescritura, donde cada regla debe incluir los campos de la siguiente tabla.

Firebase Hosting solo aplica una regla de reescritura si no existe un archivo o directorio en una ruta de URL que coincida con el patrón de URL de source o regex especificado. Cuando una solicitud activa una regla de reescritura, el navegador devuelve el contenido real del archivo de destination especificado en lugar de una redirección HTTP.

Solicitudes directas a una función

Puede usar rewrites para cumplir una función desde una URL de alojamiento de Firebase. El siguiente ejemplo es un extracto de la entrega de contenido dinámico mediante Cloud Functions .

Por ejemplo, para dirigir todas las solicitudes de la página /bigben en su sitio de Hosting para ejecutar la función 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)
  } ]
}

Después de agregar esta regla de reescritura y la implementación en Firebase (usando firebase deploy ), se puede acceder a su función a través de las siguientes URL:

• Sus subdominios de Firebase:
  PROJECT_ID .web.app/bigben y PROJECT_ID .firebaseapp.com/bigben

• Cualquier dominio personalizado conectado:
  CUSTOM_DOMAIN /bigben

Al redirigir solicitudes a funciones con Hosting, los métodos de solicitud HTTP admitidos son GET , POST , HEAD , PUT , DELETE , PATCH y OPTIONS . No se admiten otros métodos como REPORT o PROFIND .

Solicitudes directas a un contenedor de Cloud Run

Puede usar rewrites para acceder a un contenedor de Cloud Run desde una URL de alojamiento de Firebase. El siguiente ejemplo es un extracto de la entrega de contenido dinámico mediante Cloud Run .

Por ejemplo, para dirigir todas las solicitudes de la página /helloworld en su sitio de alojamiento para activar el inicio y la ejecución de una instancia de contenedor de 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)
   }
 } ]
}

Después de agregar esta regla de reescritura y la implementación en Firebase (mediante firebase deploy ), se puede acceder a la imagen de su contenedor a través de las siguientes URL:

• Sus subdominios de Firebase:
  PROJECT_ID .web.app/helloworld y PROJECT_ID .firebaseapp.com/helloworld

• Cualquier dominio personalizado conectado:
  CUSTOM_DOMAIN /helloworld

Al redirigir solicitudes a contenedores de Cloud Run con Hosting, los métodos de solicitud HTTP admitidos son GET , POST , HEAD , PUT , DELETE , PATCH y OPTIONS . No se admiten otros métodos como REPORT o PROFIND .

Actualmente, puede usar las reescrituras de Cloud Run con Hosting en las siguientes regiones:

• 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

Crear enlaces dinámicos de dominio personalizado

Puede usar rewrites para crear enlaces dinámicos de dominio personalizados. Visite la documentación de Dynamic Links para obtener información detallada sobre cómo configurar un dominio personalizado para Dynamic Links .

• Usa tu dominio personalizado solo para 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
    } ]
  }
  

• Especifique prefijos de ruta de dominio personalizados para usar con 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
    } ]
  }
  

La configuración de Dynamic Links en su archivo firebase.json requiere lo siguiente:

Configurar encabezados

Opcional
Los encabezados permiten que el cliente y el servidor pasen información adicional junto con una solicitud o una respuesta. Algunos conjuntos de encabezados pueden afectar la forma en que el navegador maneja la página y su contenido, incluido el control de acceso, la autenticación, el almacenamiento en caché y la codificación.

Especifique encabezados de respuesta personalizados y específicos del archivo mediante la creación de un atributo de headers que contenga una matriz de objetos de encabezado. En cada objeto, especifique un patrón de URL que, si coincide con la ruta de URL de la solicitud, active Hosting para aplicar los encabezados de respuesta personalizados especificados.

Esta es la estructura básica de un atributo de headers . Este ejemplo aplica un encabezado CORS para todos los archivos de fuentes.

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

El atributo de headers contiene una matriz de definiciones, donde cada definición debe incluir los campos de la siguiente tabla.

Puede obtener más información sobre Cache-Control en la sección Alojamiento que describe la entrega de contenido dinámico y el alojamiento de microservicios. También puede obtener más información sobre los encabezados CORS .

Controlar las extensiones .html

Opcional
El atributo cleanUrls le permite controlar si las URL deben incluir o no la extensión .html .

Cuando true , Hosting elimina automáticamente la extensión .html de las URL de los archivos cargados. Si se agrega una extensión .html en la solicitud, Hosting realiza una redirección 301 a la misma ruta pero elimina la extensión .html .

Aquí se explica cómo controlar la inclusión de .html en las URL al incluir un atributo cleanUrls :

"hosting": {
  // ...

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

Controlar las barras inclinadas

Opcional
El atributo trailingSlash le permite controlar si las URL de contenido estático deben incluir o no barras inclinadas.

• Cuando true , Hosting redirige las URL para agregar una barra inclinada final.
• Cuando es false , Hosting redirige las URL para eliminar una barra inclinada final.
• Cuando no se especifica, Hosting solo usa barras inclinadas finales para los archivos de índice de directorio (por ejemplo, about/index.html ).

Aquí se explica cómo controlar las barras inclinadas al agregar un atributo trailingSlash :

"hosting": {
  // ...

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

El atributo trailingSlash no afecta las reescrituras del contenido dinámico proporcionado por Cloud Functions o Cloud Run.

Coincidencia de patrones globales

Las opciones de configuración de Firebase Hosting hacen un uso extensivo de la notación de coincidencia de patrones glob con extglob, similar a cómo Git maneja las reglas de gitignore y Bower maneja las reglas de ignore . Esta página wiki es una referencia más detallada, pero las siguientes son explicaciones de ejemplos utilizados en esta página:

• firebase.json : solo coincide con el archivo firebase.json en la raíz del directorio public

• ** — Coincide con cualquier archivo o carpeta en un subdirectorio arbitrario

• * : solo coincide con archivos y carpetas en la raíz del directorio public

• **/.* — Coincide con cualquier archivo que comience con . (generalmente archivos ocultos, como en la carpeta .git ) en un subdirectorio arbitrario

• **/node_modules/** — Coincide con cualquier archivo o carpeta en un subdirectorio arbitrario de una carpeta node_modules , que a su vez puede estar en un subdirectorio arbitrario del directorio public

• **/*.@(jpg|jpeg|gif|png) — Coincide con cualquier archivo en un subdirectorio arbitrario que termina exactamente con uno de los siguientes: .jpg , .jpeg , .gif o .png

Ejemplo de configuración de Full Hosting

El siguiente es un ejemplo completo de configuración de firebase.json para Firebase Hosting. Tenga en cuenta que un archivo firebase.json también puede contener configuraciones para otros servicios de 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",

  }
}