wp_enqueue_style et Cloudflare : purger le bon cache après un déploiement

curl -sI https://exemple.fr/wp-content/themes/mon-theme/style.css | grep cf-cache-status : cette simple commande révèle en général l’origine du problème quand un client jure que « rien n’a changé » après un déploiement. La réponse affiche HIT alors que le fichier vient d’être modifié côté serveur quelques minutes plus tôt. Cloudflare sert toujours l’ancienne version depuis son cache de périphérie, et un rechargement navigateur, même en mode forcé, n’y changera rien puisque le problème se situe entre le serveur et le visiteur.

La réaction la plus fréquente consiste à vider tout le cache Cloudflare depuis le tableau de bord. Ça fonctionne, mais ça purge aussi les pages HTML, les images et tous les autres assets du site, provoquant un pic de requêtes vers l’origine juste après. Sur un site à trafic modéré, ce n’est pas dramatique ; sur un site avec plusieurs milliers de visites quotidiennes, ce genre de purge large peut faire chuter les temps de réponse pendant plusieurs minutes.

Pourquoi wp_enqueue_style ne suffit pas

Le réflexe WordPress consiste à changer la version passée à wp_enqueue_style() pour forcer le rechargement côté navigateur :

wp_enqueue_style(
    'mon-theme-main',
    get_stylesheet_uri(),
    array(),
    '1.4.2'
);

Ce paramètre de version agit uniquement sur la query string vue par le navigateur (style.css?ver=1.4.2). Or Cloudflare, par défaut, met en cache l’URL complète y compris sa query string. Si la configuration de cache du domaine ignore les paramètres de requête pour certains types de fichiers, ou si l’ancienne URL avec l’ancien numéro de version reste appelée quelque part (un plugin de cache côté serveur qui régénère une page HTML statique avec l’ancien lien, par exemple), le nouveau CSS n’est jamais sollicité et l’ancien reste servi indéfiniment.

Purger par tag plutôt que tout vider

La bonne pratique consiste à associer un Cache-Tag à l’asset du thème et à ne purger que ce tag précis lors d’un déploiement. Cela suppose un plan Cloudflare permettant les Cache-Tags (Business ou Enterprise), ou à défaut de cibler la purge par URL :

curl -X POST "https://api.cloudflare.com/client/v4/zones/ZONE_ID/purge_cache" \
  -H "Authorization: Bearer API_TOKEN" \
  -H "Content-Type: application/json" \
  --data '{"files":["https://exemple.fr/wp-content/themes/mon-theme/style.css"]}'

Ce script peut être branché en fin de pipeline de déploiement (hook post-déploiement, tâche Git côté serveur) plutôt que déclenché manuellement, ce qui évite d’oublier l’étape sous la pression d’une mise en ligne urgente.

Un versioning qui rend la purge inutile

La solution la plus robuste consiste à ne plus dépendre d’une purge du tout : générer un numéro de version basé sur le hash du contenu du fichier, ou sur son horodatage de modification, garantit une URL différente à chaque changement réel :

function mon_theme_asset_version( $chemin_relatif ) {
    $chemin_absolu = get_stylesheet_directory() . $chemin_relatif;
    return file_exists( $chemin_absolu ) ? filemtime( $chemin_absolu ) : '1.0.0';
}

wp_enqueue_style(
    'mon-theme-main',
    get_stylesheet_uri(),
    array(),
    mon_theme_asset_version( '/style.css' )
);

Avec cette approche, chaque modification de style.css produit une nouvelle URL en cache (?ver=1714399200), que Cloudflare traite comme une ressource jamais vue et sert directement depuis l’origine avant de la mettre en cache à son tour. Plus besoin de purge manuelle pour ce fichier précis.

Vérifier après coup

Après un déploiement, une vérification simple confirme que la purge ou le nouveau versioning ont fonctionné :

1. Interroger l’en-tête cf-cache-status sur l’URL de l’asset modifié.
2. MISS ou EXPIRED signale que Cloudflare est allé chercher une version fraîche à l’origine.
3. Une seconde requête juste après doit renvoyer HIT, preuve que la nouvelle version est désormais bien celle mise en cache.
4. Comparer le contenu réellement reçu avec le fichier source sur le serveur, pour écarter tout cache intermédiaire supplémentaire (cache d’hébergeur, plugin de cache serveur).

Sur nos projets, ajouter une purge ciblée en fin de script de déploiement a fait disparaître quasiment tous les tickets « le site n’est pas à jour » remontés après une mise en production de thème.

En résumé

Un CDN comme Cloudflare rend un site plus rapide, mais ajoute une couche de cache que wp_enqueue_style() seul ne maîtrise pas. Un versioning basé sur le contenu du fichier, complété par une purge ciblée par tag ou par URL en cas de besoin, évite à la fois les mises à jour invisibles et les purges globales trop coûteuses en ressources serveur.