Google is committed to advancing racial equity for Black communities. See how.
Questa pagina è stata tradotta dall'API Cloud Translation.
Switch to English

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 l'hosting?

  • Specifica quali file nella directory del tuo progetto locale desideri distribuire a Firebase Hosting. Impara come.

  • Offri una pagina 404 / Not Found personalizzata. Impara come.

  • Imposta i redirects per le pagine che hai spostato o eliminato. Impara come.

  • Imposta le rewrites per uno qualsiasi di questi scopi:

    • Mostra lo stesso contenuto per più URL. Impara come.

    • Offri una funzione o accedi a un contenitore Cloud Run da un URL di hosting. Scopri come: funzione o contenitore .

    • Crea un collegamento dinamico di dominio personalizzato. Impara come.

  • Aggiungi headers per passare ulteriori informazioni su una richiesta o una risposta, ad esempio come i browser dovrebbero gestire la pagina e il suo contenuto (autenticazione, memorizzazione nella cache, codifica, ecc.). Impara come.

  • Imposta le riscritture di internazionalizzazione (i18n) per fornire contenuti specifici in base alle preferenze di lingua e / o al paese di un utente. Scopri come (pagina diversa).

Dove definisci la tua configurazione di hosting?

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

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

Puoi controllare il contenuto firebase.json distribuito utilizzando l' API REST di hosting .

Ordine di priorità delle risposte di hosting

Le diverse opzioni di configurazione di Firebase Hosting descritte in questa pagina possono a volte 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. Contenuto statico a corrispondenza esatta
  4. Riscrizioni configurate
  5. Pagina 404 personalizzata
  6. Pagina 404 predefinita

Se stai usando le riscritture i18n , l'ordine di priorità della corrispondenza esatta e di gestione 404 viene ampliato per adattarsi al tuo "contenuto i18n".

Specifica quali file distribuire

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

La configurazione di hosting predefinita in un file firebase.json è simile a questa:

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

pubblico

necessario
L'attributo public specifica quale directory distribuire su Firebase Hosting. Il valore predefinito è una directory denominata public , ma è possibile specificare il percorso di qualsiasi directory, purché esista nella directory del progetto.

Quanto segue è il nome predefinito specificato della directory da distribuire:

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

  // ...
}

È possibile modificare il valore predefinito nella directory che si desidera distribuire:

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

  // ...
}

ignorare

Opzionale
L'attributo ignore specifica i file da ignorare durante la distribuzione. Può richiedere i 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
  ]
}

Personalizza una pagina 404 / Non trovato

Opzionale
Puoi visualizzare un errore 404 Not Found quando un utente tenta di accedere a una pagina che non esiste.

Crea un nuovo file nella directory public del tuo progetto, 404.html , quindi aggiungi il tuo contenuto 404 Not Found al file.

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

Configura i reindirizzamenti

Opzionale
Utilizza un reindirizzamento URL per evitare collegamenti interrotti 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 .

Specificare i reindirizzamenti URL creando un attributo di redirects che contiene un array di oggetti (chiamati "regole di reindirizzamento"). In ogni regola, specifica un pattern URL che, se abbinato al percorso dell'URL della richiesta, fa sì che Hosting risponda con un reindirizzamento all'URL di destinazione specificato.

Ecco la struttura di base per un attributo di 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
  } ]
}

L'attributo redirects contiene un array di regole di reindirizzamento, in cui 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 di Firebase Hosting invia una risposta di reindirizzamento HTTP dicendo al browser di effettuare una nuova richiesta all'URL di destination .

Campo Descrizione
redirects
source (consigliato)
o regex

Un pattern URL che, se abbinato all'URL della richiesta iniziale, attiva Hosting per applicare il reindirizzamento

destination

Un URL statico in cui il browser dovrebbe effettuare una nuova richiesta

Questo URL può essere un percorso relativo o assoluto.

type

Il codice di risposta HTTP

  • Usa un tipo di 301 per "Spostato in modo permanente"
  • Utilizza un tipo di 302 per "Trovato" (reindirizzamento temporaneo)

Acquisisci segmenti di URL per i reindirizzamenti

Opzionale
A volte, potrebbe essere necessario acquisire segmenti specifici del pattern URL di una regola di reindirizzamento (valore source o regex ), quindi riutilizzare questi segmenti nel percorso di destination della regola.

Configura le riscritture

Opzionale
Usa una riscrittura per mostrare lo stesso contenuto per più URL. Le riscritture sono particolarmente utili con la corrispondenza dei pattern, poiché puoi accettare qualsiasi URL che corrisponde al pattern e lasciare che il codice lato client decida 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 URL che corrisponde alla source specificata o al pattern URL regex , al browser verrà fornito il contenuto del file nell'URL di destination .

Specificare le riscritture dell'URL creando un attributo di rewrites che contiene un array di oggetti (chiamate "regole di riscrittura"). In ogni regola, specifica un pattern URL che, se abbinato al percorso dell'URL della richiesta, fa sì che Hosting risponda come se al servizio fosse stato fornito l'URL di destinazione specificato.

Ecco la struttura di base per un attributo di rewrites . Questo esempio serve index.html per richieste 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"
  } ]
}

L'attributo rewrites contiene una matrice di regole di riscrittura, in cui ciascuna 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 source specificata o al pattern URL regex . Quando una richiesta attiva una regola di riscrittura, il browser restituisce il contenuto effettivo del file di destination specificato invece di un reindirizzamento HTTP.

Campo Descrizione
rewrites
source (consigliato)
o regex

Un pattern URL che, se abbinato all'URL della richiesta iniziale, attiva Hosting per applicare la riscrittura

destination

Un file locale che deve esistere

Questo URL può essere un percorso relativo o assoluto.

Richieste dirette a una funzione

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

Ad esempio, per indirizzare tutte le richieste dalla pagina /bigben sul tuo sito di hosting per eseguire la funzione bigben :

"hosting": {
  // ...

  // Directs all requests from the page `/bigben` to execute the `bigben` function
  "rewrites": [ {
    "source": "/bigben",
    "function": "bigben"
  } ]
}

Dopo aver aggiunto questa regola di riscrittura e aver firebase deploy a Firebase (utilizzando la distribuzione di Firebase), 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

Richieste dirette a un container Cloud Run

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

Ad esempio, per indirizzare tutte le richieste dalla pagina /helloworld sul tuo sito di hosting per attivare l'avvio e l'esecuzione di helloworld contenitore 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 e aver firebase deploy in Firebase (utilizzando la distribuzione di Firebase), l'immagine del contenitore è 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

È possibile utilizzare le rewrites per creare collegamenti dinamici di dominio personalizzati. Visita la documentazione di Dynamic Links per informazioni dettagliate sulla configurazione di un dominio personalizzato per Dynamic Links .

  • Utilizza il tuo dominio personalizzato solo per i link dinamici

    "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 i collegamenti dinamici

    "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 collegamenti dinamici nel file firebase.json richiede quanto segue:

Campo Descrizione
appAssociation

Deve essere impostato su AUTO

  • Se non includi questo attributo nella configurazione, l'impostazione predefinita per appAssociation è AUTO .
  • Impostando questo attributo su AUTO , Hosting può generare dinamicamente file assetlinks.json e apple-app-site-association quando vengono richiesti.
rewrites
source

Un percorso che desideri utilizzare per Dynamic Links

A differenza delle regole che riscrivono i percorsi degli URL, le regole di riscrittura per Dynamic Links non possono contenere espressioni regolari.

dynamicLinks Deve essere impostato su true

Configura le intestazioni

Opzionale
Le intestazioni consentono al client e al server di passare informazioni aggiuntive insieme a una richiesta o una risposta. Alcuni set di intestazioni possono influenzare il modo in cui il browser gestisce la pagina e il suo contenuto, inclusi il controllo dell'accesso, l'autenticazione, la memorizzazione nella cache e la codifica.

Specificare intestazioni di risposta personalizzate e specifiche del file creando un attributo headers che contiene una matrice di oggetti di intestazione. In ogni oggetto, specifica un pattern URL che, se abbinato 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 a tutti i file di font.

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

L'attributo headers contiene un array di definizioni, in cui ciascuna definizione deve includere i campi nella tabella seguente.

Campo Descrizione
headers
source (consigliato)
o regex

Un pattern URL che, se abbinato all'URL della richiesta iniziale, attiva Hosting per applicare l'intestazione personalizzata

Per creare un'intestazione da abbinare alla tua pagina 404 personalizzata , utilizza 404.html come source o valore regex .

matrice di (sotto) headers

Le intestazioni personalizzate che Hosting applica al percorso della richiesta

Ogni sottointestazione deve includere una coppia key e value (vedere le due righe successive).

key Il nome dell'intestazione, ad esempio Cache-Control
value Il valore dell'intestazione, ad esempio max-age=7200

Puoi saperne di più su Cache-Control nella sezione Hosting che descrive la fornitura di contenuto dinamico e l'hosting di microservizi. Puoi anche saperne di più sulle intestazioni CORS .

Controlla le estensioni .html

Opzionale
L'attributo cleanUrls ti 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 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
}

Controlla le barre finali

Opzionale
L'attributo trailingSlash consente di controllare se gli URL di contenuto statico devono includere o meno barre finali.

  • Quando è true , Hosting reindirizza gli URL per aggiungere una barra finale.
  • Se false , Hosting reindirizza gli URL per rimuovere una barra finale.
  • Quando non specificato, Hosting utilizza solo le barre finali per i file di indice di 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 nel contenuto dinamico servito da Cloud Functions o Cloud Run.

Corrispondenza del modello globale

Firebase opzioni di configurazione di hosting fanno largo uso del pattern matching glob notazione con extglob, simile a come le maniglie di Git gitignore regole e Bower maniglie ignore regole. Questa pagina wiki è un riferimento più dettagliato, ma le seguenti sono spiegazioni di 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: .jpg , .jpeg , .gif o .png

Esempio di configurazione di hosting completo

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

  }
}