Configura il comportamento di Hosting

Con Firebase Hosting, puoi configurare un comportamento di hosting personalizzato per le richieste al tuo sito.

Cosa puoi configurare per Hosting?

• Specifica i file nella directory del progetto locale che vuoi eseguire il deployment su Firebase Hosting. Scopri come.

• Pubblica una pagina 404/Non trovato personalizzata. Scopri come.

• Configura redirects per le pagine che hai spostato o eliminato. Scopri come.

• Configura rewrites per uno dei seguenti scopi:

  • Mostra gli stessi contenuti per più URL. Scopri come.

  • Pubblica una funzione o accedi a un container Cloud Run da un URL Hosting. Scopri come: funzione o container.

  • Crea un dominio personalizzato Dynamic Link. Scopri come.

• Aggiungi headers per trasmettere informazioni aggiuntive su una richiesta o una risposta, ad esempio come i browser devono gestire la pagina e i relativi contenuti (autenticazione, memorizzazione nella cache, codifica e così via). Scopri come.

• Configura le riscritture per l'internazionalizzazione (i18n) in modo da pubblicare contenuti specifici in base alle preferenze di lingua e/o al paese di un utente. Scopri come (pagina diversa).

Dove definisci la configurazione di Hosting?

Definisci la configurazione di Firebase Hosting nel file firebase.json. Firebase crea automaticamente il file firebase.json nella directory principale del progetto quando esegui il comando firebase init.

In fondo a questa pagina puoi trovare un esempio di configurazione firebase.json completo (che copre solo Firebase Hosting). Tieni presente che un file firebase.json può contenere anche configurazioni per altri servizi Firebase.

Puoi controllare i contenuti firebase.json di cui è stato eseguito il deployment utilizzando l'API REST Hosting.

Ordine di priorità delle risposte di Hosting

Le diverse opzioni di configurazione di Firebase Hosting descritte in questa pagina a volte possono sovrapporsi. In caso di conflitto, Hosting determina la sua risposta utilizzando il seguente ordine di priorità:

1. Spazi dei nomi riservati che iniziano con un segmento di percorso /__/*
2. Reindirizzamenti configurati
3. Contenuti statici con corrispondenza esatta
4. Configurato riscritture
5. Pagina Personalizza pagina 404
6. Pagina 404 predefinita

Se utilizzi le riscritture i18n, l'ordine di priorità della corrispondenza esatta e della gestione degli errori 404 viene ampliato per adattarsi ai tuoi "contenuti i18n".

Specificare i file da implementare

Gli attributi predefiniti, public e ignore, inclusi nel file firebase.json predefinito, definiscono quali file nella directory del progetto devono essere implementati nel progetto Firebase.

La configurazione hosting predefinita in un file firebase.json ha il seguente aspetto:

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

pubblica

Obbligatorio
L'attributo public specifica la directory in cui eseguire il deployment Firebase Hosting. Il valore predefinito è una directory denominata public, ma puoi specificare il percorso di qualsiasi directory, purché esista nella directory del progetto.

Di seguito è riportato il nome predefinito specificato della directory da implementare:

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

  // ...
}

Puoi modificare il valore predefinito nella directory in cui vuoi eseguire il deployment:

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

  // ...
}

ignora

(Facoltativo)
L'attributo ignore specifica i file da ignorare durante il deployment. Può accettare glob� nello stesso modo in cui Git� gestisce .gitignore.

Di seguito sono riportati i valori predefiniti per i file da ignorare:

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

Personalizzare una pagina 404/Non trovato

(Facoltativo)
Puoi mostrare un errore 404 Not Found personalizzato quando un utente tenta di accedere a una pagina che non esiste.

Crea un nuovo file nella directory public del tuo progetto, chiamalo 404.html, quindi aggiungi i tuoi contenuti 404 Not Found personalizzati al file.

Firebase Hosting mostrerà i contenuti di questa pagina 404.html personalizzata se un browser attiva un errore 404 Not Found sul tuo dominio o sottodominio.

Configurare i reindirizzamenti

(Facoltativo)
Utilizza un reindirizzamento URL per evitare link non funzionanti se hai spostato una pagina o per abbreviare gli URL. Ad esempio, puoi reindirizzare un browser da example.com/team a example.com/about.html.

Specifica i reindirizzamenti URL creando un attributo redirects che contiene un array di oggetti (chiamati "regole di reindirizzamento"). In ogni regola, specifica un pattern URL che, se corrisponde al percorso dell'URL della richiesta, attiva Hosting per rispondere con un reindirizzamento all'URL di destinazione specificato.

Ecco la struttura di base per un attributo redirects. Questo esempio reindirizza le richieste a /foo effettuando una nuova richiesta 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
  } ]
}

L'attributo redirects contiene un array di regole di reindirizzamento, dove ogni regola deve includere i campi nella tabella seguente.

Firebase Hosting confronta il valore source o regex con tutti i percorsi URL all'inizio di ogni richiesta (prima che il browser determini se esiste un file o una cartella in quel percorso). Se viene trovata una corrispondenza, il server di origine Firebase Hosting invia una risposta di reindirizzamento HTTPS che indica al browser di effettuare una nuova richiesta all'URL destination.

Acquisire segmenti di URL per i reindirizzamenti

(Facoltativo)
A volte, potresti dover acquisire segmenti specifici di un pattern URL di una regola di reindirizzamento (valore source o regex), per poi riutilizzarli nel percorso destination della regola.

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

Configurare le riscritture

Facoltativo
Utilizza una riscrittura per mostrare gli stessi contenuti per più URL. Le riscritture sono particolarmente utili con la corrispondenza dei pattern, in quanto puoi accettare qualsiasi URL che corrisponda al pattern e lasciare che il codice lato client decida cosa visualizzare.

Puoi anche utilizzare le riscritture per supportare le app che utilizzano HTML5 pushState per la navigazione. Quando un browser tenta di aprire un percorso URL che corrisponde al pattern URL source o regex specificato, il browser riceverà invece i contenuti del file all'URL destination.

Specifica le riscritture degli URL creando un attributo rewrites che contiene un array di oggetti (chiamati "regole di riscrittura"). In ogni regola, specifica un pattern URL che, se corrisponde al percorso dell'URL della richiesta, attiva Hosting per rispondere come se al servizio fosse stato fornito l'URL di destinazione specificato.

Ecco la struttura di base per un attributo rewrites. Questo esempio restituisce index.html per le richieste di file o directory che non esistono.

"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'attributo rewrites contiene un array di regole di riscrittura, dove ogni regola deve includere i campi nella tabella seguente.

Firebase Hosting applica una regola di riscrittura solo se un file o una directory non esiste in un percorso URL che corrisponde al pattern URL source o regex specificato. Quando una richiesta attiva una regola di riscrittura, il browser restituisce i contenuti effettivi del file destination specificato anziché un reindirizzamento HTTP.

Richieste dirette a una funzione

Puoi utilizzare rewrites per pubblicare una funzione da un URL Firebase Hosting. L'esempio seguente è un estratto di pubblicazione di contenuti dinamici utilizzando Cloud Functions.

Ad esempio, per indirizzare tutte le richieste dalla pagina /bigben sul tuo sito Hosting all'esecuzione della funzione 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)
    }
  } ]
}

Dopo aver aggiunto questa regola di riscrittura ed eseguito il deployment su Firebase (utilizzando firebase deploy), la tua funzione è raggiungibile tramite i seguenti URL:

• I tuoi sottodomini Firebase:
  PROJECT_ID.web.app/bigben e PROJECT_ID.firebaseapp.com/bigben

• Eventuali domini personalizzati collegati:
  CUSTOM_DOMAIN/bigben

Quando reindirizzi le richieste alle funzioni con Hosting, i metodi di richiesta HTTP supportati sono GET, POST, HEAD, PUT, DELETE, PATCH e OPTIONS. Altri metodi come REPORT o PROFIND non sono supportati.

Richieste dirette a un container Cloud Run

Puoi utilizzare rewrites per accedere a un contenitore Cloud Run da un URL Firebase Hosting. L'esempio seguente è un estratto di pubblicazione di contenuti dinamici utilizzando Cloud Run.

Ad esempio, per indirizzare tutte le richieste dalla pagina /helloworld del tuo sito Hosting per attivare l'avvio e l'esecuzione di un'istanza di container 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)
   }
 } ]
}

Dopo aver aggiunto questa regola di riscrittura ed eseguito il deployment su Firebase (utilizzando firebase deploy), l'immagine del container è raggiungibile tramite i seguenti URL:

• I tuoi sottodomini Firebase:
  PROJECT_ID.web.app/helloworld e PROJECT_ID.firebaseapp.com/helloworld

• Eventuali domini personalizzati collegati:
  CUSTOM_DOMAIN/helloworld

Quando reindirizzi le richieste ai contenitori Cloud Run con Hosting, i metodi di richiesta HTTP supportati sono GET, POST, HEAD, PUT, DELETE, PATCH e OPTIONS. Altri metodi come REPORT o PROFIND non sono supportati.

Per ottenere le migliori prestazioni, esegui il colocation del servizio Cloud Run con Hosting utilizzando le seguenti regioni:

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

Le riscritture a Cloud Run da Hosting sono supportate nelle seguenti regioni:

• 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

Crea un dominio personalizzato Dynamic Links

Puoi utilizzare rewrites per creare un dominio personalizzato Dynamic Links. Visita la documentazione di Dynamic Links per informazioni dettagliate su come configurare un dominio personalizzato per Dynamic Links.

• Utilizza il tuo dominio personalizzato solo per 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
    } ]
  }

• Specifica i prefissi del percorso del dominio personalizzato da utilizzare per 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 configurazione di Dynamic Links nel file firebase.json richiede quanto segue:

Configurare le intestazioni

(Facoltativo)
Le intestazioni consentono al client e al server di trasmettere informazioni aggiuntive insieme a una richiesta o a una risposta. Alcuni set di intestazioni possono influire sul modo in cui il browser gestisce la pagina e i relativi contenuti, tra cui controllo dell'accesso, autenticazione, memorizzazione nella cache e codifica.

Specifica intestazioni di risposta personalizzate e specifiche per il file creando un attributo headers che contiene un array di oggetti di intestazione. In ogni oggetto, specifica un pattern URL che, se corrisponde al percorso dell'URL della richiesta, attiva Hosting per applicare le intestazioni di risposta personalizzate specificate.

Ecco la struttura di base per un attributo headers. Questo esempio applica un'intestazione CORS per tutti i file dei caratteri.

"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'attributo headers contiene un array di definizioni, in cui ogni definizione deve includere i campi nella tabella seguente.

Puoi scoprire di più su Cache-Control nella sezione Hosting che descrive la pubblicazione di contenuti dinamici e l'hosting di microservizi. Puoi anche scoprire di più sulle intestazioni CORS.

Controllare le estensioni .html

(Facoltativo)
L'attributo cleanUrls ti consente di controllare se gli URL devono includere l'estensione .html.

Quando true, Hosting elimina automaticamente l'estensione .html dagli URL dei file caricati. Se nella richiesta viene aggiunta un'estensione .html, Hosting esegue un reindirizzamento 301 allo stesso percorso, ma elimina l'estensione .html.

Ecco come controllare l'inclusione di .html negli URL includendo un attributo cleanUrls:

"hosting": {
  // ...

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

Controllare le barre finali

Facoltativo
L'attributo trailingSlash ti consente di controllare se gli URL dei contenuti statici devono includere barre finali.

• Quando true, Hosting reindirizza gli URL per aggiungere una barra finale.
• Quando false, Hosting reindirizza gli URL per rimuovere una barra finale.
• Se non specificato, Hosting utilizza le barre finali solo per i file indice delle directory (ad esempio, about/index.html).

Ecco come controllare le barre finali aggiungendo un attributo trailingSlash:

"hosting": {
  // ...

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

L'attributo trailingSlash non influisce sulle riscritture dei contenuti dinamici pubblicati da Cloud Functions o Cloud Run.

Corrispondenza dei pattern glob

Le opzioni di configurazione di Firebase Hosting utilizzano ampiamente la notazione di corrispondenza dei pattern glob con extglob, in modo simile a come Git gestisce le regole gitignore e Bower gestisce le regole ignore. Questa pagina wiki è un riferimento più dettagliato, ma di seguito sono riportate le spiegazioni degli esempi utilizzati in questa pagina:

• firebase.json: corrisponde solo al file firebase.json nella radice della directory public

• **: corrisponde a qualsiasi file o cartella in una sottodirectory arbitraria

• *: corrisponde solo a file e cartelle nella radice della directory public

• **/.*: corrisponde a qualsiasi file che inizia con . (di solito file nascosti, come nella cartella .git) in una sottodirectory arbitraria

• **/node_modules/**: corrisponde a qualsiasi file o cartella in una sottodirectory arbitraria di una cartella node_modules, che a sua volta può trovarsi in una sottodirectory arbitraria della directory public

• **/*.@(jpg|jpeg|gif|png): corrisponde a qualsiasi file in una sottodirectory arbitraria che termina con esattamente uno dei seguenti elementi: .jpg, .jpeg, .gif o .png

Esempio di configurazione completa di Hosting

Di seguito è riportato un esempio di configurazione firebase.json completo per Firebase Hosting. Tieni presente che un file firebase.json può contenere anche configurazioni per altri servizi 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",

  }
}