Worker e Pagine: distribuzione, routing e cosa nasconde ogni modello

Quando un team adotta Cloudflare Workers, la prima implementazione è banale: wrangler deploy, tutto qui, lo script è attivo. Quando un altro team adotta Pages, anche la prima distribuzione è banale: connettere il repository GitHub, configurare il comando build, il gioco è fatto. Il problema si presenta quando i due coesistono nella stessa zona, quando è necessaria un'anteprima per ramo o quando qualcuno ha bisogno di controllare cosa è in esecuzione in produzione senza accedere al dashboard.

Come vengono distribuiti i lavoratori

L'artefatto centrale di un progetto Workers è wrangler.toml. Contiene percorsi, associazioni, variabili di ambiente, limiti di compatibilità e ambienti. Una tipica distribuzione di produzione/staging si presenta così nello stesso file:

name = "minha-api"
main = "src/index.ts"
compatibility_date = "2024-09-23"

[[routes]]
pattern = "api.exemplo.com/*"
zone_name = "exemplo.com"

[env.staging]
name = "minha-api-staging"
[[env.staging.routes]]
pattern = "api-staging.exemplo.com/*"
zone_name = "exemplo.com"

Questa è una configurazione con versione nel codice, rivedibile nelle richieste pull, tracciabile nella cronologia Git. Qualsiasi modifica al percorso o all'associazione passa attraverso lo stesso processo di revisione del codice.

wrangler deploy --env staging distribuisce lo script come un lavoratore separato (minha-api-staging), con i propri percorsi e collegamenti. Gli ambienti in Workers sono Worker distinti, non varianti della stessa distribuzione.

Come viene distribuito Pages

Le pagine funzionano tramite git push. Connetti un repository, definisci il comando di compilazione e la directory di output sulla dashboard e ogni push al ramo principale attiva una pipeline: clona, installa, crea, carica le risorse sulla CDN. La pipeline prevede fino a 500 build/mese nel piano gratuito e 5.000/mese nel piano a pagamento ($ 20/mese).

La grande differenza operativa: ogni push su qualsiasi ramo diverso da quello principale genera una distribuzione di anteprima automatica con un URL univoco nel formato hash-branch.seuprojet.pages.dev. Apri una richiesta pull, Cloudflare commenta il PR con l'URL di anteprima. Il team del prodotto testa l'URL prima di approvare l'unione. Workers non ha un equivalente nativo per questo.

La limitazione simmetrica: le impostazioni di creazione delle pagine (comando di creazione, variabili di ambiente, versione del nodo) si trovano nella dashboard, non nel file di codice. Ad oggi, non esiste un supporto completo per Pages. Ciò significa che le modifiche alla configurazione della build non passano attraverso richieste pull e non sono nella cronologia Git. Per i team che necessitano di un audit trail completo dell'infrastruttura, questo rappresenta un vero attrito.

Routing e trappola delle collisioni del percorso

I lavoratori utilizzano modelli di percorso collegati a una zona. Il modello api.exemplo.com/v1/* cattura tutte le richieste per questo percorso e le consegna allo script corrispondente. Se due diversi Worker tentano di registrare lo stesso modello nella stessa zona, la seconda distribuzione fallisce con un errore di conflitto.

Pages utilizza un sottodominio dedicato (*.pages.dev) o un dominio personalizzato collegato al progetto. Quando utilizzi un dominio personalizzato in Pages, Cloudflare crea un lavoratore interno che serve le risorse e le instrada alle Funzioni. Questo lavoratore interno occupa i percorsi del dominio.

Il problema concreto: hai un progetto Pages in app.exemplo.com e desideri aggiungere un Worker separato per elaborare i webhook in app.exemplo.com/webhooks. Non dà. I percorsi delle pagine già catturano app.exemplo.com/*. La soluzione è spostare il gestore dei webhook su una funzione Pages in /functions/webhooks.ts o utilizzare un sottodominio separato (webhooks.exemplo.com) con un lavoratore indipendente.

La precedenza di routing all'interno delle Pagine segue un ordine fisso: _redirects viene elaborato per primo, poi _headers, quindi le Funzioni in /functions e infine le risorse statiche. Ciò significa che una funzione in /functions/blog/[slug].ts ha la priorità su un file statico in /blog/qualquer-coisa.html, il che potrebbe sorprendere se generassi pagine statiche con lo stesso percorso.

Ambienti di pagina e cosa manca

Pages ha il concetto di ambienti di produzione e anteprima. La produzione è il ramo principale; qualsiasi altro ramo genera un'anteprima. È possibile configurare le variabili di ambiente separate per ambiente nel dashboard.

Cosa non ha Pages: più ambienti con nome con diverse configurazioni di build. Workers consente wrangler deploy --env staging con un insieme di vincoli e variabili completamente diverso. In Pages, se desideri un ambiente di staging con un database D1 diverso, crea un progetto Pages separato e gestisci manualmente la sincronizzazione tra i due.

Per i team che lavorano con una gestione temporanea rigorosa (database separato, chiavi API sandbox, flag di funzionalità distinti) questa limitazione è significativa e generalmente spinge questi carichi di lavoro sui lavoratori.

Come wrangler.toml va (parzialmente) a Pages

Cloudflare ha annunciato il supporto sperimentale nel 2020 per la configurazione dei collegamenti di Pages Functions: spazi dei nomi KV, database D1, variabili di ambiente. Ciò risolve parte del problema della traccia di controllo: i collegamenti rimangono nel codice. Ma la pipeline di compilazione (comando, directory di output, versione del nodo) è ancora sulla dashboard.

Lo stato attuale è parziale. Coloro che necessitano oggi di una configurazione del codice al 100% utilizzano Workers con risorse servite tramite R2 + Cache API, rinunciando al CDN gratuito di Pages. Questo è un vero compromesso che vale la pena calcolare prima di prendere una decisione.

Cosa valutare prima di decidere

Il modello di distribuzione di Pages offre due risorse concrete: pipeline di creazione integrata (nessun CI esterno da assemblare) e distribuzioni di anteprima automatiche per ramo. Per i team di progettazione e prodotto che esaminano le funzionalità prima della fusione, l'anteprima del ramo accelera in modo misurabile il ciclo di revisione.

Workers offre una configurazione del codice verificabile fin dal primo giorno, ambienti denominati con associazioni distinte e supporto per trigger non HTTP (cron, code, e-mail) di cui Pages non dispone. Per le API o i servizi senza una componente visiva che necessitano di una messa in scena rigorosa, i lavoratori strutturati con wrangler.toml ben organizzati sono operativamente più puliti.

La collisione di percorsi tra progetti nella stessa zona è il problema più comune per i team che iniziano con Pages e poi provano ad aggiungere Worker isolati. La mappatura mentale corretta: un dominio personalizzato in Pages è come un Workers che occupa il jolly di quel dominio. Tutto ciò che desideri su quel dominio deve vivere all'interno del progetto Pages.