Configura il comportamento di Hosting

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

Cosa puoi configurare per Hosting?

• Specifica i file nella directory del progetto locale in cui vuoi eseguire il deploymentFirebase Hosting. Scopri come.

• Mostra una pagina 404/Non trovata 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 contenitore 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 su una risposta, ad esempio la modalità di gestione della pagina e dei relativi contenuti da parte dei browser (autenticazione, memorizzazione nella cache, codifica e così via). Scopri come.

• Configura le riscritture di internazionalizzazione (i18n) per pubblicare contenuti specifici in base alla preferenza della lingua e/o al paese dell'utente. Scopri come (pagina diversa).

Dove definisci la configurazione Hosting?

Devi definire 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 è disponibile un esempio completo di configurazione di firebase.json (che riguarda solo Firebase Hosting). Tieni presente che un file firebase.json può anche contenere 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à di Hosting risposte

Le diverse opzioni di configurazione di Firebase Hosting descritte in questa pagina a volte possono sovrapporsi. In caso di conflitto, Hosting determina la 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. Riscritture configurate
5. Pagina 404 personalizzata
6. Pagina 404 predefinita

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

Specifica i file di cui eseguire il deployment

Gli attributi predefiniti (public e ignore) inclusi nel file firebase.json predefinito definiscono i file della directory del progetto di cui deve essere eseguito il deployment nel progetto Firebase.

La configurazione predefinita di hosting in un file firebase.json è la seguente:

"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 deploymentFirebase 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 in base alla directory che 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, assegnagli il nome 404.html e aggiungi al file i tuoi contenuti 404 Not Found personalizzati.

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 inaccessibili se hai spostato una pagina o per abbreviare gli URL. Ad esempio, potresti reindirizzare un browser da example.com/team a example.com/about.html.

Specifica i reindirizzamenti URL creando un attributo redirects contenente 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 di un attributo redirects. Questo esempio reindirizza le richieste a /foo inviando 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, in cui ogni regola deve includere i campi riportati 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 i segmenti di URL per i reindirizzamenti

Facoltativo
A volte, potresti dover acquisire segmenti specifici del pattern URL (valore source o regex) di una regola di reindirizzamento, 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 pattern, in quanto puoi accettare qualsiasi URL che corrisponde al pattern e lasciare che sia il codice lato client a decidere cosa visualizzare.

Puoi anche utilizzare le riscritture per supportare le app che utilizzano pushState HTML5 per la navigazione. Quando un browser tenta di aprire un percorso dell'URL che corrisponde al pattern URL source o regex specificato, al browser verranno invece forniti i contenuti del file nell'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 corrispondente al percorso dell'URL della richiesta, attivi la risposta di Hosting come se al servizio fosse stato fornito l'URL di destinazione specificato.

Ecco la struttura di base di un attributo rewrites. Questo esempio serve per le richieste di index.html a 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, in cui ogni regola deve includere i campi riportati nella tabella seguente.

Firebase Hosting applica una regola di riscrittura solo se un file o una directory non esiste in un percorso dell'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.

Indirizzare le richieste a una funzione

Puoi utilizzare rewrites per eseguire una funzione da un URL Firebase Hosting. L'esempio seguente è un estratto della 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 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.

Indirizzare le richieste a un contenitore Cloud Run

Puoi utilizzare rewrites per accedere a un contenitore Cloud Run da un URL Firebase Hosting. L'esempio seguente è un estratto della 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 in Firebase (utilizzando firebase deploy), l'immagine 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 le richieste vengono reindirizzate 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 il massimo rendimento, esegui la colocazione del servizio Cloud Run con Hosting utilizzando le seguenti regioni:

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

Le riscritture in 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 il dominio personalizzato Dynamic Links. Consulta 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 dei percorsi dei domini personalizzati 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:

Configura le intestazioni

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

Specifica intestazioni delle risposte personalizzate e specifiche per il file creando un attributo headers contenente un array di oggetti di intestazione. In ogni oggetto, specifica un pattern URL che, se corrispondente al percorso dell'URL della richiesta, attiva Hosting per l'applicazione delle intestazioni delle risposte personalizzate specificate.

Di seguito è riportata la struttura di base di 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 riportati nella tabella seguente.

Per ulteriori informazioni su Cache-Control, consulta la 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 consente di controllare se gli URL devono includere o meno l'estensione .html.

Quando true, Hosting elimina automaticamente l'estensione .html dagli URL dei file caricati. Se alla 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 consente di controllare se gli URL dei contenuti statici devono includere o meno le barre finali.

• Quando true, Hosting reindirizza gli URL in modo da 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 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 di pattern glob

Le opzioni di configurazione di Firebase Hosting fanno ampio uso della corrispondenza del pattern glob con extglob, in modo simile al modo in cui 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 directory principale della directory public

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

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

• **/.*: corrisponde a qualsiasi file che inizia con . (in genere 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 può trovarsi a sua volta 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 valori: .jpg, .jpeg, .gif o .png

Esempio di configurazione completa di Hosting

Di seguito è riportato un esempio completo di configurazione di firebase.json 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",

  }
}