Workers et Pages : déploiement, routage et ce que cache chaque modèle

Lorsqu'une équipe adopte Cloudflare Workers, le premier déploiement est trivial : wrangler deploy, ça y est, le script est live. Lorsqu'une autre équipe adopte Pages, le premier déploiement est également trivial : connecter le référentiel GitHub, configurer la commande build, c'est tout. Le problème apparaît lorsque les deux cohabitent dans la même zone, lorsque vous avez besoin d'un aperçu par branche ou lorsque quelqu'un doit auditer ce qui s'exécute en production sans accéder au tableau de bord.

Comment les Workers se déploient

L'artefact central d'un projet Workers est wrangler.toml. Il contient des routes, des liaisons, des variables d'environnement, des limites de compatibilité et des environnements. Un déploiement de production/préproduction typique ressemble à ceci dans le même fichier :

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"

Il s'agit d'une configuration versionnée dans le code, consultable dans les demandes d'extraction, traçable dans l'historique Git. Tout changement d’itinéraire ou de liaison passe par le même processus de révision de code.

wrangler deploy --env staging déploie le script en tant que Worker distinct (minha-api-staging), avec ses propres routes et liaisons. Les environnements dans Workers sont des Workers distincts, et non des variantes du même déploiement.

Comment Pages se déploie

Les pages fonctionnent via git push. Vous connectez un référentiel, définissez la commande de build et le répertoire de sortie sur le tableau de bord, et chaque push vers la branche principale déclenche un pipeline : cloner, installer, construire, télécharger les actifs sur le CDN. Le pipeline gère jusqu'à 500 builds/mois sur le forfait gratuit et 5 000/mois sur le forfait payant (20 $/mois).

La grande différence opérationnelle : chaque push vers une branche autre que la principale génère un déploiement automatique en prévisualisation avec une URL unique au format hash-branch.seuprojet.pages.dev. Vous ouvrez une pull request, Cloudflare commente le PR avec l'URL d'aperçu. L'équipe produit teste l'URL avant d'approuver la fusion. Workers n’a pas d’équivalent natif pour cela.

La limitation symétrique : les paramètres de construction des pages (commande de construction, variables d'environnement, version du nœud) se trouvent sur le tableau de bord, pas dans le fichier de code. À ce jour, il n’existe pas de support wrangler.toml complet pour Pages. Cela signifie que les modifications de configuration de build ne passent pas par les demandes d'extraction et ne sont pas dans l'historique Git. Pour les équipes qui ont besoin d’une piste d’audit complète de l’infrastructure, il s’agit d’une véritable friction.

Routage et piège de collision d'itinéraire

Les travailleurs utilisent des modèles d'itinéraire liés à une zone. Le modèle api.exemplo.com/v1/* capture toutes les requêtes pour ce chemin et les transmet au script correspondant. Si deux Workers différents tentent d'enregistrer le même modèle dans la même zone, le deuxième déploiement échoue avec une erreur de conflit.

Pages utilise un sous-domaine dédié (*.pages.dev) ou un domaine personnalisé lié au projet. Lorsque vous utilisez un domaine personnalisé dans Pages, Cloudflare crée un Worker interne qui sert les actifs et les achemine vers les fonctions. Ce Worker interne occupe les routes du domaine.

Le problème concret : vous avez un projet Pages en app.exemplo.com et souhaitez ajouter un Worker distinct pour traiter les webhooks en app.exemplo.com/webhooks. Cela ne donne pas. Les itinéraires des pages capturent déjà app.exemplo.com/*. La solution consiste à déplacer le gestionnaire de webhooks vers une fonction Pages dans /functions/webhooks.ts, ou à utiliser un sous-domaine distinct (webhooks.exemplo.com) avec un Worker indépendant.

La priorité de routage au sein de Pages suit un ordre fixe : _redirects est traité en premier, puis _headers, puis les fonctions dans /functions et enfin les ressources statiques. Cela signifie qu'une fonction dans /functions/blog/[slug].ts a la priorité sur un fichier statique dans /blog/qualquer-coisa.html — ce qui peut être surprenant si vous avez généré des pages statiques avec le même chemin.

Environnements de page et ce qui manque

Pages a le concept d’environnements de production et de prévisualisation. La production est la branche principale ; toute autre branche génère un aperçu. Vous pouvez configurer des variables d'environnement séparées par environnement sur le tableau de bord.

Ce que Pages n'a pas : plusieurs environnements nommés avec différentes configurations de build. Workers autorise wrangler deploy --env staging avec un ensemble complètement différent de liaisons et de variables. Dans Pages, si vous souhaitez un environnement intermédiaire avec une base de données D1 différente, vous créez un projet Pages distinct et gérez manuellement la synchronisation entre les deux.

Pour les équipes qui travaillent avec une mise en scène stricte (base de données séparée, clés API sandbox, indicateurs de fonctionnalités distincts), cette limitation est importante et transfère généralement ces charges de travail vers les Workers.

Comment wrangler.toml va (partiellement) vers Pages

Cloudflare a annoncé un support expérimental en 2020 pour la configuration des liaisons Pages Functions : espaces de noms KV, bases de données D1, variables d'environnement. Cela résout une partie du problème de la piste d'audit : les liaisons restent dans le code. Mais le pipeline de build (commande, répertoire de sortie, version du nœud) est toujours sur le tableau de bord.

L’état actuel est partiel. Ceux qui ont besoin aujourd’hui d’une configuration de code à 100 % utilisent Workers avec des actifs servis via l’API R2 + Cache, abandonnant ainsi le CDN Pages gratuit. Il s’agit d’un véritable compromis qui mérite d’être calculé avant de prendre la décision.

Que faut-il évaluer avant de décider

Le modèle de déploiement Pages offre deux atouts concrets : un pipeline de build intégré (pas de CI externe à assembler) et des déploiements automatiques en prévisualisation par branche. Pour les équipes de conception et de produit qui examinent les fonctionnalités avant la fusion, l’aperçu des branches accélère considérablement le cycle de révision.

Workers propose une configuration de code vérifiable dès le premier jour, des environnements nommés avec des liaisons distinctes et une prise en charge des déclencheurs non HTTP (cron, files d'attente, courrier électronique) que Pages n'a pas. Pour les API ou les services sans composant visuel qui nécessitent une mise en scène rigoureuse, les Workers structurés avec des wrangler.toml bien organisés sont plus propres sur le plan opérationnel.

La collision de routes entre des projets dans la même zone est le problème le plus courant pour les équipes qui commencent avec Pages et tentent ensuite d'ajouter des Workers isolés. La cartographie mentale correcte : un domaine personnalisé dans Pages est comme un Workers qui occupe le caractère générique de ce domaine. Tout ce que vous souhaitez sur ce domaine doit résider dans le projet Pages.