L’hosting su Cloudflare Pages consente ai team frontend di distribuire codice veloce, sicuro e senza l’onere dell’amministrazione dei server. Utilizzando Cloudflare Pages , gli sviluppatori ottengono una piattaforma edge-native ad alte prestazioni per distribuire applicazioni web statiche, applicazioni a pagina singola (SPA) e framework con rendering lato server (SSR). Collegandosi direttamente al tuo repository Git, Cloudflare automatizza le pipeline di build, genera distribuzioni di anteprima e ospita le risorse a livello globale. Questa guida spiega come connettere Git, configurare le impostazioni di build, impostare domini personalizzati e configurare i reindirizzamenti.

Punti chiave da ricordare:

  • Distribuzione di app frontend edge-native; Cloudflare Pages serve le risorse a livello globale direttamente dalla rete di Cloudflare, garantendo tempi di caricamento inferiori al secondo.
  • Integrazione Git automatizzata; collega il tuo repository per attivare build automatiche e generare URL di anteprima per ogni commit.
  • Configurazione delle impostazioni di build dei framework; imposta le cartelle di output e i comandi per React, Vue, Next.js, Hugo o Astro.
  • Applicazione di regole di reindirizzamento e header utilizzando file di testo semplici _redirects e _headers posizionati nella cartella pubblica.
  • Associazione di domini personalizzati con certificati SSL gratuiti gestiti direttamente da Cloudflare e rinnovati in modo automatico.

Cos’è Cloudflare Pages?

Cloudflare Pages è una piattaforma di hosting serverless per sviluppatori frontend, simile a Netlify o Vercel, costruita direttamente sulla rete globale di Cloudflare.

Piuttosto che ospitare file su un singolo server cloud, Cloudflare Pages distribuisce file HTML, CSS, JavaScript e immagini in posizioni edge in tutto il mondo. Quando un utente richiede il tuo sito, le risorse vengono servite dalla posizione più vicina, riducendo la latenza di rete. Per i progetti che richiedono una logica lato server, Pages si integra con Cloudflare Workers per eseguire funzioni di backend. Per confrontare Pages con altri servizi di edge computing, leggi la nostra guida su Cloudflare Pages vs. Workers .

Prerequisiti

Prima di iniziare, assicurati di avere i seguenti elementi pronti:

  • Un repository Git su GitHub o GitLab contenente il tuo progetto (o i file compilati pronti per un caricamento diretto).
  • Un framework che produce risorse statiche – React (Vite), Vue, Astro, SvelteKit, Hugo o HTML semplice. I framework con rendering lato server funzionano ugualmente, attraverso le Pages Functions.
  • Una build locale funzionante. Esegui il comando di build (ad esempio npm run build) e conferma che la cartella di output venga generata senza errori prima di procedere al collegamento.
  • Un account Cloudflare gratuito. Non è richiesta alcuna carta di credito per il piano gratuito.
  • Node.js installato localmente (consigliato) in modo da poter riprodurre le build ed utilizzare lo strumento Wrangler da riga di comando.

Un rapido controllo preliminare evita ore di debug: se il tuo sito non si compila correttamente sulla tua macchina, non si compilerà nemmeno sui runner di Cloudflare. Risolvi prima gli errori locali.

Passo 1: Collegamento del tuo repository Git

Per iniziare, accedi alla tua dashboard di Cloudflare, naviga su Compute > Pages e fai clic su Create a project.

Seleziona Connect to Git per collegare il tuo account GitHub o GitLab. Scegli il repository che contiene la tua applicazione web statica. Questa integrazione è preziosa perché stabilisce una pipeline di integrazione continua (CI): ogni volta che invii codice al tuo branch di produzione, Cloudflare compila e pubblica gli aggiornamenti automaticamente. Per gli altri commit, Cloudflare genera “URL di anteprima” univoci in modo da poter testare le modifiche prima del merge.

Passo 2: Configurazione delle impostazioni di build

Cloudflare Pages supporta i generatori di siti statici e i framework frontend più diffusi. Durante la configurazione guidata, imposta i seguenti parametri in base al tuo stack tecnologico:

  • Build command: Lo script di build definito nel tuo package.json (come npm run build o hugo --minify).
  • Build output directory: La cartella contenente i file statici compilati (come dist, build o public).
  • Environment variables: Se lo script richiede chiavi API o variabili di configurazione, definiscile qui.

Cloudflare rileva automaticamente molti framework, ma confermare le impostazioni predefinite evita il fallimento della prima build. Le combinazioni tipiche sono:

FrameworkComando di buildCartella di output
React (Vite)npm run builddist
React (Create React App)npm run buildbuild
Next.js (esportazione statica)npx next buildout
Astronpm run builddist
Vue (Vite)npm run builddist
SvelteKitnpm run build.svelte-kit/cloudflare
Hugohugo --minifypublic

Fissa la versione di Node. Una causa frequente di problemi in cui la build “funziona localmente, fallisce su Cloudflare” è una discrepanza tra la versione di Node predefinita del runner e quella prevista dal tuo progetto. Dichiarala esplicitamente, come variabile d’ambiente nella dashboard:

1NODE_VERSION = 20

Oppure inviando un file .node-version nella root del repository:

120

Passo 3: Configurazione di reindirizzamenti e header

Per le applicazioni a pagina singola (come React Router) o le migrazioni di URL precedenti, devi configurare le regole di routing e di reindirizzamento. Pages gestisce questo aspetto attraverso semplici file di testo posizionati nella cartella di output.

Reindirizzamenti (_redirects)

Crea un file chiamato _redirects nella tua cartella pubblica (public). Affinché una SPA React gestisca in modo pulito il routing lato client, aggiungi la regola di fallback:

1/*  /index.html  200

Questo forza tutte le richieste a risolversi su index.html, consentendo al router JavaScript di gestire il percorso.

L’ordine delle regole è importante. Cloudflare valuta le regole dall’alto verso il basso e si ferma alla prima corrispondenza, quindi i reindirizzamenti specifici devono trovarsi sopra il fallback generale:

1# Permanent redirect for a moved page
2/old-pricing   /pricing            301
3
4# Redirect an entire section, preserving the sub-path
5/blog/*        /articles/:splat    301
6
7# SPA fallback (must come last)
8/*             /index.html         200

Il segnaposto :splat trasferisce la parte corrispondente del percorso alla destinazione. Il piano gratuito consente fino a 2.000 regole di reindirizzamento statico per progetto. Oltre questo limite, sposta la logica in una Pages Function o utilizza i Bulk Redirects.

Header personalizzati (_headers)

Crea un file chiamato _headers per applicare regole di sicurezza, Referrer-Policy o controlli di cache personalizzati:

1/*
2  X-Frame-Options: DENY
3  X-Content-Type-Options: nosniff
4  Referrer-Policy: strict-origin-when-cross-origin

Questo file è anche il posto giusto per regolare il caching. Le risorse con hash e immutabili possono essere memorizzate nella cache per un anno, mentre l’HTML deve rimanere fresco in modo che gli utenti ricevano sempre l’ultima build:

1/assets/*
2  Cache-Control: public, max-age=31536000, immutable

Per vedere come si comportano queste regole rispetto al routing di backend tradizionale, leggi la creazione di un’API serverless con Cloudflare Workers .

Passo 4: Associazione dei domini personalizzati

Una volta distribuito il progetto, Cloudflare fornisce un sottodominio predefinito (ad esempio tuo-progetto.pages.dev).

Per associare il tuo dominio personalizzato, vai alla scheda Custom Domains nel tuo progetto Pages e inserisci il tuo dominio (ad esempio tuaazienda.it). Se il tuo DNS è gestito da Cloudflare, la piattaforma configura i record CNAME e fornisce istantaneamente un certificato SSL gratuito che si rinnova automaticamente. Se hai bisogno di aiuto per gestire l’associazione del dominio, i DNS o la sicurezza del server, consulta la pagina dell’auditing sulla sicurezza del sito web .

Passo 5: Distribuzione con la CLI Wrangler (Caricamento diretto)

L’integrazione Git è adatta per la maggior parte dei team, ma puoi anche distribuire direttamente dalla tua macchina o da una pipeline esistente utilizzando Wrangler, lo strumento da riga di comando di Cloudflare. Questo è utile quando la build viene già eseguita in GitHub Actions o GitLab CI e desideri solo caricare l’output finito.

Installa Wrangler ed effettua l’accesso:

1npm install -g wrangler
2wrangler login

Esegui la build locale, quindi carica la cartella di output in un progetto con un nome specifico:

1npm run build
2wrangler pages deploy ./dist --project-name=my-web-app

La prima esecuzione crea il progetto se non esiste già. Nelle pipeline CI, sostituisci il comando interattivo wrangler login con un token API fornito tramite una variabile d’ambiente, in modo che non sia necessario alcun passaggio nel browser:

1# .github/workflows/deploy.yml (excerpt)
2- name: Deploy to Cloudflare Pages
3  run: npx wrangler pages deploy ./dist --project-name=my-web-app
4  env:
5    CLOUDFLARE_API_TOKEN: ${{ secrets.CLOUDFLARE_API_TOKEN }}
6    CLOUDFLARE_ACCOUNT_ID: ${{ secrets.CLOUDFLARE_ACCOUNT_ID }}

Il caricamento diretto salta la fase di compilazione di Cloudflare, il che evita problemi legati all’ambiente di build e ti dà il controllo completo sulla toolchain.

Problemi comuni e risoluzione

Una serie di problemi ricorrenti spiega la maggior parte dei fallimenti di distribuzione iniziali:

  • Errori 404 durante il caricamento di una route SPA. Un percorso lato client come /dashboard restituisce “Nothing is here yet” perché non esiste alcun file corrispondente sul disco. La soluzione è la regola di fallback /* /index.html 200 in _redirects. Assicurati che questo file finisca nella cartella di output della build e non nella cartella dei sorgenti.
  • I file _redirects o _headers vengono ignorati. Questi file devono trovarsi nella cartella di output pubblicata, non solo nel repository. Con Vite, Astro o SvelteKit, posizionali nella cartella public/ (o static/) in modo che la build li copi in modo inalterato.
  • La build funziona localmente ma fallisce su Cloudflare. Solitamente è causato da un disallineamento della versione di Node o da una variabile d’ambiente mancante per la build. Fissa la versione di Node e dichiara nuovamente le variabili necessarie.
  • Troppi file o dimensioni eccessive. Un singolo deployment è limitato a 20.000 file, con un limite di 25 MiB per file. I media di grandi dimensioni dovrebbero essere archiviati su R2 o su un servizio di hosting di immagini esterno, non nel bundle statico.
  • Risorse obsolete dopo un rilascio. I file con hash come app.4f2c.js possono essere memorizzati in cache in modo aggressivo, ma l’HTML non dovrebbe esserlo. Mantieni l’HTML su una cache breve.

Test e considerazioni per la produzione

Cloudflare crea un deployment di anteprima per ogni branch non di produzione e ogni pull request, ciascuno sul proprio URL (ad esempio abc123.my-web-app.pages.dev). Poiché le anteprime vengono eseguite sulla stessa rete edge del tuo sito live, rappresentano un luogo affidabile per esaminare le modifiche prima del merge.

Per i rilasci reali, alcuni controlli fanno la differenza tra un semplice host e un flusso di lavoro affidabile:

  • Rollback. Ogni deployment viene conservato, quindi un rilascio difettoso può essere annullato promuovendo nuovamente una build precedente in produzione dalla dashboard in pochi secondi, senza ricompilare.
  • Separazione degli ambienti. Imposta variabili diverse per produzione e anteprima, in modo che le build di anteprima puntino ad API di staging anziché ai dati reali.
  • Analytics e Core Web Vitals. Abilita Cloudflare Web Analytics – incentrato sulla privacy e senza cookie – per monitorare i valori reali di LCP, CLS e il traffico degli utenti senza caricare uno script di terze parti.
  • Controllo degli accessi per le anteprime. Gli URL di anteprima sono pubblici per impostazione predefinita. Se un branch espone lavoro non ancora rilasciato, proteggilo con Cloudflare Access in modo che solo il tuo team possa aprirlo.

Implementare questi accorgimenti fin da subito mantiene i deployment prevedibili man mano che il progetto cresce e più persone vi contribuiscono.

Punti chiave da considerare

  • Cloudflare Pages ospita applicazioni web statiche sulla rete edge globale di Cloudflare, ottimizzando le velocità di caricamento.
  • Automatizza i deployment collegando GitHub o GitLab per compilare il codice ad ogni commit.
  • Definisci i comandi di build e le cartelle di output corrispondenti al tuo framework (Astro, Next.js, Hugo, React).
  • Configura i reindirizzamenti e gli header di sicurezza utilizzando file di testo semplici _redirects e _headers nella cartella di output.
  • Associa domini personalizzati con certificati SSL gratuiti e rinnovati automaticamente gestiti direttamente da Cloudflare.

Ottimizza la tua infrastruttura web

La distribuzione di frontend veloci e sicuri richiede la scelta della giusta architettura di hosting e delle giuste regole di caching. Mecanik è specializzata in servizi di sviluppo siti web e offre servizi professionali di audit SEO tecnico . Creiamo piattaforme React, Next.js e Astro personalizzate, ottimizzate per i Core Web Vitals e distribuite su Cloudflare. Contattaci oggi stesso per discutere del tuo prossimo progetto.

Domande frequenti (FAQ)

Cos’è l’hosting di Cloudflare Pages? Si tratta di una piattaforma di hosting frontend serverless che compila e distribuisce applicazioni web statiche, SPA React e output di generatori di siti statici (come Astro o Hugo) a livello globale sulla CDN di Cloudflare.

Cloudflare Pages supporta il rendering lato server (SSR)? Sì. Pages supporta i framework SSR (come Next.js, Astro, SvelteKit) convertendo automaticamente la logica del server in Cloudflare Workers serverless durante il processo di build.

Come si configurano i reindirizzamenti su Cloudflare Pages? Crea un file di testo semplice chiamato _redirects nella cartella di output della build e scrivi le regole di reindirizzamento definendo il percorso sorgente, il percorso di destinazione e il codice di stato HTTP.

Cloudflare Pages è gratuito? Sì. Cloudflare Pages offre un piano gratuito generoso che include deployment illimitati, larghezza di banda illimitata e domini personalizzati, rappresentando una soluzione altamente conveniente.

Come posso configurare un dominio personalizzato su Pages? Accedi alla scheda Custom Domains nel pannello di controllo del tuo progetto Pages, inserisci il tuo nome di dominio e Cloudflare configurerà i record DNS ed emetterà un certifictato SSL gratuito.