Configurer le comportement d'hébergement

Firebase Hosting vous permet de configurer un comportement d'hébergement personnalisé pour les requêtes adressées à votre site.

Quels sont les paramètres que vous pouvez configurer pour Hosting ?

• Spécifiez les fichiers du répertoire de votre projet local que vous souhaitez déployer sur Firebase Hosting. En savoir plus

• Proposez une page 404/introuvable personnalisée. En savoir plus

• Configurez redirects pour les pages que vous avez déplacées ou supprimées. En savoir plus

• Configurez rewrites pour l'un des objectifs suivants :

  • afficher le même contenu pour plusieurs URL. En savoir plus

  • Diffuser une fonction ou accéder à un conteneur Cloud Run à partir d'une URL Hosting Découvrez comment : fonction ou conteneur.

  • Créez un domaine personnaliséDynamic Link. En savoir plus

• Ajoutez headers pour transmettre des informations supplémentaires sur une requête ou une réponse, par exemple sur la façon dont les navigateurs doivent gérer la page et son contenu (authentification, mise en cache, encodage, etc.). En savoir plus

• Configurez des réécritures d'internationalisation (i18n) pour diffuser des contenus spécifiques en fonction de la langue et/ou du pays de l'utilisateur. En savoir plus (autre page)

Où définissez-vous la configuration de votre Hosting ?

Vous définissez votre configuration Firebase Hosting dans votre fichier firebase.json. Firebase crée automatiquement votre fichier firebase.json à la racine du répertoire de votre projet lorsque vous exécutez la commande firebase init.

Vous trouverez un exemple de configuration firebase.json complet (ne couvrant que Firebase Hosting) en bas de cette page. Notez qu'un fichier firebase.json peut également contenir des configurations pour d'autres services Firebase.

Vous pouvez vérifier le contenu firebase.json déployé à l'aide de l'API REST Hosting.

Ordre de priorité des réponses Hosting

Les différentes options de configuration Firebase Hosting décrites sur cette page peuvent parfois se chevaucher. En cas de conflit, Hosting détermine sa réponse en fonction de l'ordre de priorité suivant :

1. Espaces de noms réservés commençant par un segment de chemin d'accès /__/*
2. Redirections configurées
3. Contenu statique en correspondance exacte
4. Réécritures configurées
5. Page 404 personnalisée
6. Page 404 par défaut

Si vous utilisez des réécritures i18n, l'ordre de priorité de la gestion des correspondances exactes et des erreurs 404 est étendu pour s'adapter à votre "contenu i18n".

Spécifier les fichiers à déployer

Les attributs par défaut public et ignore inclus dans le fichier firebase.json par défaut définissent les fichiers du répertoire de votre projet qui doivent être déployés dans votre projet Firebase.

La configuration hosting par défaut dans un fichier firebase.json se présente comme suit :

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

publique

Obligatoire
L'attribut public spécifie le répertoire dans lequel effectuer le déploiement Firebase Hosting. La valeur par défaut est un répertoire nommé public, mais vous pouvez spécifier le chemin d'accès de n'importe quel répertoire, à condition qu'il existe dans le répertoire de votre projet.

Voici le nom spécifié par défaut du répertoire à déployer :

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

  // ...
}

Vous pouvez remplacer la valeur par défaut par le répertoire que vous souhaitez déployer :

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

  // ...
}

ignorer

Facultatif
L'attribut ignore spécifie les fichiers à ignorer lors du déploiement. Il peut prendre des globaux de la même manière que Git gère .gitignore.

Voici les valeurs par défaut pour les fichiers à ignorer :

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

Personnaliser une page 404/Page introuvable

Facultatif
Vous pouvez diffuser une erreur 404 Not Found personnalisée lorsqu'un utilisateur tente d'accéder à une page qui n'existe pas.

Créez un fichier dans le répertoire public de votre projet, nommez-le 404.html, puis ajoutez-y votre contenu 404 Not Found personnalisé.

Firebase Hosting affichera le contenu de cette page 404.html personnalisée si un navigateur déclenche une erreur 404 Not Found sur votre domaine ou sous-domaine.

Configurer les redirections

Facultatif
Utilisez une redirection d'URL pour éviter les liens rompus si vous avez déplacé une page ou pour raccourcir les URL. Par exemple, vous pouvez rediriger un navigateur de example.com/team vers example.com/about.html.

Spécifiez les redirections d'URL en créant un attribut redirects contenant un tableau d'objets (appelé "règles de redirection"). Dans chaque règle, spécifiez un format d'URL qui, s'il correspond au chemin d'URL de la requête, déclenche Hosting pour répondre avec une redirection vers l'URL de destination spécifiée.

Voici la structure de base d'un attribut redirects. Cet exemple redirige les requêtes vers /foo en envoyant une nouvelle requête à /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
  } ]
}

L'attribut redirects contient un tableau de règles de redirection, où chaque règle doit inclure les champs du tableau ci-dessous.

Firebase Hosting compare la valeur source ou regex à tous les chemins d'URL au début de chaque requête (avant que le navigateur ne détermine si un fichier ou un dossier existe à ce chemin). Si une correspondance est trouvée, le serveur d'origine Firebase Hosting envoie une réponse de redirection HTTPS indiquant au navigateur d'envoyer une nouvelle requête à l'URL destination.

Capturer les segments d'URL pour les redirections

Facultatif
Il peut arriver que vous deviez capturer des segments spécifiques du modèle d'URL d'une règle de redirection (valeur source ou regex), puis les réutiliser dans le chemin destination de la règle.

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

Configurer les réécritures

Facultatif
Utilisez une réécriture pour afficher le même contenu pour plusieurs URL. Les réécritures sont particulièrement utiles avec la correspondance de modèles, car vous pouvez accepter n'importe quelle URL correspondant au modèle et laisser le code côté client décider de ce qu'il faut afficher.

Vous pouvez également utiliser des réécritures pour prendre en charge les applications qui utilisent HTML5 pushState pour la navigation. Lorsqu'un navigateur tente d'ouvrir un chemin d'URL correspondant au format d'URL source ou regex spécifié, le contenu du fichier à l'URL destination est fourni au navigateur.

Spécifiez les réécritures d'URL en créant un attribut rewrites contenant un tableau d'objets (appelés "règles de réécriture"). Dans chaque règle, spécifiez un format d'URL qui, s'il correspond au chemin d'URL de la requête, déclenche Hosting pour qu'il réponde comme si le service avait reçu l'URL de destination spécifiée.

Voici la structure de base d'un attribut rewrites. Cet exemple diffuse index.html pour les requêtes de fichiers ou de répertoires qui n'existent pas.

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

L'attribut rewrites contient un tableau de règles de réécriture, où chaque règle doit inclure les champs du tableau ci-dessous.

Firebase Hosting n'applique une règle de réécriture que si aucun fichier ni répertoire n'existe au niveau d'un chemin d'URL correspondant au format d'URL source ou regex spécifié. Lorsqu'une requête déclenche une règle de réécriture, le navigateur renvoie le contenu réel du fichier destination spécifié au lieu d'une redirection HTTP.

Requêtes directes à une fonction

Vous pouvez utiliser rewrites pour diffuser une fonction à partir d'une URL Firebase Hosting. L'exemple suivant est un extrait de Diffusion de contenu dynamique à l'aide de Cloud Functions.

Par exemple, pour diriger toutes les requêtes de la page /bigben de votre site Hosting vers l'exécution de la fonction bigben :

"hosting": {
  // ...

  // Directs all requests from the page `/bigben` to execute the `bigben` function
  "rewrites": [ {
    "source": "/bigben",
    "function": {
      "functionId": "bigben",
      "region": "us-central1"  // optional (see note below)
      "pinTag": true           // optional (see note below)
    }
  } ]
}

Après avoir ajouté cette règle de réécriture et déployé sur Firebase (à l'aide de firebase deploy), votre fonction est accessible via les URL suivantes :

• Vos sous-domaines Firebase :
  PROJECT_ID.web.app/bigben et PROJECT_ID.firebaseapp.com/bigben

• Tous les domaines personnalisés associés :
  CUSTOM_DOMAIN/bigben

Lorsque vous redirigez des requêtes vers des fonctions avec Hosting, les méthodes de requête HTTP compatibles sont GET, POST, HEAD, PUT, DELETE, PATCH et OPTIONS. Les autres méthodes, telles que REPORT ou PROFIND, ne sont pas acceptées.

Adresser des requêtes directement à un conteneur Cloud Run

Vous pouvez utiliser rewrites pour accéder à un conteneur Cloud Run à partir d'une URL Firebase Hosting. L'exemple suivant est un extrait de Diffusion de contenu dynamique à l'aide de Cloud Run.

Par exemple, pour que toutes les requêtes de la page /helloworld de votre site Hosting déclenchent le démarrage et l'exécution d'une instance de conteneur 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)
   }
 } ]
}

Après avoir ajouté cette règle de réécriture et déployé sur Firebase (à l'aide de firebase deploy), votre image de conteneur est accessible via les URL suivantes :

• Vos sous-domaines Firebase :
  PROJECT_ID.web.app/helloworld et PROJECT_ID.firebaseapp.com/helloworld

• Tous les domaines personnalisés associés :
  CUSTOM_DOMAIN/helloworld

Lorsque vous redirigez des requêtes vers des conteneurs Cloud Run avec Hosting, les méthodes de requête HTTP acceptées sont GET, POST, HEAD, PUT, DELETE, PATCH et OPTIONS. Les autres méthodes, comme REPORT ou PROFIND, ne sont pas acceptées.

Pour des performances optimales, colocalisez votre service Cloud Run avec Hosting à l'aide des régions suivantes :

• us-west1
• us-central1
• us-east1
• europe-west1
• asia-east1

Les réécritures vers Cloud Run à partir de Hosting sont disponibles dans les régions suivantes :

• asia-east1
• asia-east2
• asia-northeast1
• asia-northeast2
• asia-northeast3
• asia-south1
• asia-south2
• asia-southeast1
• asia-southeast2
• australia-southeast1
• australia-southeast2
• europe-central2
• europe-north1
• europe-southwest1
• europe-west1
• europe-west12
• europe-west2
• europe-west3
• europe-west4
• europe-west6
• europe-west8
• europe-west9
• me-central1
• me-west1
• northamerica-northeast1
• northamerica-northeast2
• southamerica-east1
• southamerica-west1
• us-central1
• us-east1
• us-east4
• us-east5
• us-south1
• us-west1
• us-west2
• us-west3
• us-west4
• us-west1
• us-central1
• us-east1
• europe-west1
• asia-east1

Créer un domaine personnalisé Dynamic Links

Vous pouvez utiliser rewrites pour créer le domaine personnalisé Dynamic Links. Consultez la documentation Dynamic Links pour obtenir des informations détaillées sur la configuration d'un domaine personnalisé pour Dynamic Links.

• Utiliser uniquement votre domaine personnalisé pour 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
    } ]
  }

• Spécifiez les préfixes de chemin de domaine personnalisé à utiliser pour 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
    } ]
  }

Pour configurer Dynamic Links dans votre fichier firebase.json, vous devez effectuer les opérations suivantes :

Configurer les en-têtes

Facultatif
Les en-têtes permettent au client et au serveur de transmettre des informations supplémentaires avec une requête ou une réponse. Certains ensembles d'en-têtes peuvent affecter la façon dont le navigateur gère la page et son contenu, y compris le contrôle des accès, l'authentification, la mise en cache et l'encodage.

Spécifiez des en-têtes de réponse personnalisés et spécifiques à un fichier en créant un attribut headers contenant un tableau d'objets d'en-tête. Dans chaque objet, spécifiez un modèle d'URL qui, s'il correspond au chemin d'URL de la requête, déclenche l'application des en-têtes de réponse personnalisés spécifiés par Hosting.

Voici la structure de base d'un attribut headers. Cet exemple applique un en-tête CORS à tous les fichiers de police.

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

L'attribut headers contient un tableau de définitions, où chaque définition doit inclure les champs du tableau ci-dessous.

Pour en savoir plus sur Cache-Control, consultez la section Hosting qui décrit la diffusion de contenu dynamique et l'hébergement de microservices. Vous pouvez également en savoir plus sur les en-têtes CORS.

Contrôler les extensions .html

Facultatif
L'attribut cleanUrls vous permet de contrôler si les URL doivent inclure l'extension .html.

Lorsque true, Hosting supprime automatiquement l'extension .html des URL de fichiers importés. Si une extension .html est ajoutée à la requête, Hosting effectue une redirection 301 vers le même chemin, mais supprime l'extension .html.

Pour contrôler l'inclusion de .html dans les URL en incluant un attribut cleanUrls :

"hosting": {
  // ...

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

Contrôler les barres obliques de fin

Facultatif
L'attribut trailingSlash vous permet de contrôler si les URL de contenu statique doivent inclure des barres obliques de fin.

• Lorsque true, Hosting redirige les URL pour ajouter une barre oblique à la fin.
• Lorsque la valeur est false, Hosting redirige les URL pour supprimer la barre oblique finale.
• Lorsqu'il n'est pas spécifié, Hosting n'utilise les barres obliques de fin que pour les fichiers d'index de répertoire (par exemple, about/index.html).

Voici comment contrôler les barres obliques de fin en ajoutant un attribut trailingSlash :

"hosting": {
  // ...

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

L'attribut trailingSlash n'a pas d'incidence sur la réécriture du contenu dynamique diffusé par Cloud Functions ou Cloud Run.

Correspondance de modèles glob

Les options de configuration Firebase Hosting utilisent largement la notation de correspondance de modèles glob avec extglob, de la même manière que Git gère les règles gitignore et Bower gère les règles ignore. Cette page wiki est une référence plus détaillée, mais voici des explications sur les exemples utilisés sur cette page :

• firebase.json : ne correspond qu'au fichier firebase.json à la racine du répertoire public

• ** : correspond à n'importe quel fichier ou dossier dans un sous-répertoire arbitraire.

• * : ne correspond qu'aux fichiers et dossiers à la racine du répertoire public

• **/.* : correspond à n'importe quel fichier commençant par . (généralement des fichiers cachés, comme dans le dossier .git) dans un sous-répertoire arbitraire.

• **/node_modules/** : correspond à n'importe quel fichier ou dossier dans un sous-répertoire arbitraire d'un dossier node_modules, qui peut lui-même se trouver dans un sous-répertoire arbitraire du répertoire public.

• **/*.@(jpg|jpeg|gif|png) : correspond à n'importe quel fichier d'un sous-répertoire arbitraire se terminant par l'une des extensions suivantes : .jpg, .jpeg, .gif ou .png.

Exemple de configuration Hosting complète

Voici un exemple de configuration firebase.json complète pour Firebase Hosting. Notez qu'un fichier firebase.json peut également contenir des configurations pour d'autres services 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",

  }
}