Aller au contenu

Servir WordPress sous forme de HTML statique

La plupart des pages d’un site marketing ou de documentation sont identiques pour tous les visiteurs anonymes. WordPress démarre quand même, charge toutes les extensions, exécute le thème et affiche les blocs à chaque requête. Une extension de mise en cache des pages peut aider, mais elle ajoute un élément à gérer, avec ses propres règles sur ce qui peut être stocké sans risque.

Blockstudio propose un pré-rendu statique facultatif. Il stocke des documents HTML anonymes complets dans son propre répertoire de cache et, si vous l’autorisez, les sert depuis un fichier d’extension advanced-cache.php avant le démarrage de WordPress. Toute la configuration se fait dans blockstudio.json.

Ce guide vous accompagne pas à pas pour activer la fonctionnalité, vérifier ce qui est mis en cache ou non, expliquer la règle qui protège les visiteurs connectés, puis terminer par une configuration CDN qui ne met en cache que ce que l’origine indique comme pouvant l’être.

Comment une requête est servie

Lorsque le pré-rendu est activé, une requête admissible suit l’une de ces trois voies :

  1. Résultat anticipé. Le fichier d’extension trouve un document stocké dans sa table de routes et le transmet avant le chargement de WordPress. La réponse contient X-Blockstudio-Static-Prerender: HIT-EARLY.
  2. Résultat en cache. WordPress démarre, puis à template_redirect Blockstudio trouve un document stocké encore valide et l’envoie au lieu d’afficher le modèle. La réponse contient X-Blockstudio-Static-Prerender: HIT.
  3. Échec du cache. WordPress affiche la page normalement. Si le visiteur est anonyme et que le résultat est un document HTML complet avec le statut 200, Blockstudio le stocke pour la requête suivante.

Les requêtes non admissibles ne touchent jamais au cache.

Étape 1 : activer le profil et le cache

Commencez par activer le profil de performances et le pré-rendu, en laissant la diffusion anticipée désactivée :

JSON
{
  "$schema": "https://blockstudio.dev/schema/blockstudio",
  "performance": {
    "profile": "speed",
    "staticPrerender": {
      "enabled": true,
      "ttl": 86400,
      "earlyServe": false,
      "dynamicPaths": ["/account", "/checkout", "/login"],
      "warm": {
        "enabled": true,
        "interval": 900,
        "concurrency": 4
      }
    }
  }
}

Rôle de chaque élément :

  • profile: "speed" active les réglages de production par défaut pour l’interface publique : le bruit dans l’en-tête, la découverte oEmbed, XML-RPC et les ressources génériques de l’interface publique du cœur sont supprimés, et les liens de même origine sont préchargés selon l’intention. Commencez par tester le réglage de suppression des ressources de l’interface publique du cœur : une page qui en dépend sera visiblement cassée. Toute valeur enfant remplace le profil.
  • staticPrerender.enabled enregistre l’environnement d’exécution. Tant qu’il est false, la fonctionnalité n’écrit aucun fichier et n’enregistre aucun hook de requête.
  • ttl définit l’âge maximal d’un document stocké en secondes (valeur par défaut : 86400).
  • dynamicPaths répertorie les préfixes de chemin qui doivent toujours être générés à la demande.
  • warm planifie un préchauffage en arrière-plan qui régénère les URL publiques obsolètes toutes les interval secondes.

La ligne $schema couvre toutes les clés ; un éditeur prenant en charge le schéma JSON signalera donc une erreur telle que "ttl": 0 (la valeur minimale est 1).

Étape 2 : savoir ce qui est admissible

Blockstudio applique des critères prudents à ce qu’il stocke. Ces requêtes contournent toujours le cache :

  • tout ce qui n’est pas GET
  • tout URL avec une chaîne de requête
  • wp-admin, wp-json, wp-login.php, xmlrpc.php, Ajax et cron
  • les flux, les recherches et les chemins d’aperçu
  • les requêtes qui envoient un en-tête X-WP-Nonce
  • les chemins sous dynamicPaths
  • les visiteurs avec un cookie wordpress_logged_in_*, wp-postpass_* ou comment_author_email_*, sauf si serveLoggedIn est activé

Les chemins dynamiques sont mis en correspondance selon les limites des segments de chemin. Avec la configuration ci-dessus :

Requête Contourné
/pricing/ non
/account/orders/ oui
/accounting/ non
/checkout oui
/pricing/?utm_source=x oui
/blog/feed/ oui

Lors du stockage, seul un document complet est conservé : la réponse doit commencer par <!doctype html ou <html, avoir le statut 200 et ne pas contenir le marqueur de désactivation. Un modèle qui ne doit jamais être stocké peut afficher ce marqueur n’importe où dans la page :

HTML
<!-- blockstudio:no-cache -->

Les pages d’erreur ne sont jamais stockées : une page 404 personnalisée ne peut donc jamais être servie comme une page réussie.

Étape 3 : vérifier les résultats en cache

Consultez quelques pages en fenêtre privée, puis demandez à Blockstudio ce qu’il contient :

Shell
wp bs prerender status
JSON
{
    "enabled": true,
    "invalidate": "signature",
    "identity": "e6cdd3fcda14ad6ded85a763bd01a33b",
    "cacheRoot": ".../wp-content/blockstudio/cache/sites/.../static-prerender",
    "files": 0,
    "bytes": 0,
    "records": 0,
    "queue": {
        "pending": 0,
        "processing": 0,
        "done": 0,
        "unique": 0,
        "bytes": 0
    },
    ...
    "diagnostics": []
}

files et bytes augmentent à mesure que les documents sont stockés, queue indique le retard du préchauffage et diagnostics contient les compteurs de résultats, d’échecs de cache, de compilations et d’erreurs pour chaque périmètre. Pour vérifier une page précise, demandez-la deux fois en tant que visiteur anonyme et recherchez l’en-tête :

Shell
curl -s -o /dev/null -D - https://example.com/pricing/ | grep -i x-blockstudio-static-prerender

La deuxième réponse contient X-Blockstudio-Static-Prerender: HIT. Utilisez un GET comme ci-dessus : curl -I envoie une requête HEAD, qui contourne toujours le cache.

Étape 4 : servir avant le démarrage de WordPress

Une fois les résultats vérifiés, définissez "earlyServe": true. Blockstudio gère alors trois petits éléments d’état : un fichier d’extension wp-content/advanced-cache.php, une table de routes wp-content/blockstudio-static-prerender-map.php partagée et une déclaration WP_CACHE dans wp-config.php. Ils sont installés lors de la prochaine requête d’administration.

Quelques règles assurent la sécurité sur les hébergements mutualisés et les installations multisites :

  • Blockstudio ne remplace jamais un drop-in, une carte ou une ligne WP_CACHE dont il n’est pas propriétaire. Si un autre plugin de cache possède déjà advanced-cache.php, le service anticipé reste désactivé.
  • Si WP_CACHE est déjà défini sur true, wp-config.php reste inchangé. Sur les hébergeurs où wp-config.php n’est pas accessible en écriture, définissez-le vous-même.
  • Avant le service, le drop-in et le chemin PHP vérifient tous deux que la feuille de style Tailwind liée par le document, dont le nom contient un hachage du contenu, existe toujours. Si ce n’est pas le cas, la requête est envoyée à WordPress au lieu d’être servie sans style.
  • Les entrées multisite partagent une carte, mais sont isolées par hôte, chemin d’accueil et identifiant de site.
  • Les en-têtes de réponse nommés dans replayHeaders — Link par défaut — sont stockés avec chaque document et renvoyés à chaque réponse ; ainsi, un en-tête Link qu’une page envoie avec header() est conservé lors du service anticipé. Les en-têtes de cookie et de mise en cache ne sont jamais rejoués.

Les accès anticipés portent X-Blockstudio-Static-Prerender: HIT-EARLY. Désactiver earlyServe ou enabled supprime une fois l’état appartenant à Blockstudio, et wp bs teardown le supprime explicitement pour les installations Composer qui n’ont pas de hook de désactivation.

Visiteurs connectés et balisage identique

Par défaut, les visiteurs connectés reçoivent toujours un rendu en direct. Le réglage "serveLoggedIn": true leur permet aussi d’utiliser un document déjà stocké, ce qui rend le site aussi rapide pour les éditeurs et les clients que pour les visiteurs anonymes.

Les réponses personnalisées ne créent jamais d’entrées de cache : en cas d’absence dans le cache, un visiteur connecté reçoit un rendu en direct qui n’est pas stocké. La conséquence est facile à manquer. Avec serveLoggedIn activé, un visiteur connecté reçoit le document anonyme lorsqu’il existe, et un rendu personnalisé en direct uniquement lorsqu’il n’existe pas. Toute branche de modèle qui dépend de l’utilisateur actuel ne s’affiche qu’en cas d’absence dans le cache ; la même page change donc d’une visite à l’autre, et la branche personnalisée est de fait inopérante sur les routes en cache.

La règle qui en découle : sur chaque route en dehors de dynamicPaths, le balisage des visiteurs connectés doit être identique octet par octet à celui des visiteurs anonymes. Cela signifie qu’aucune branche is_user_logged_in() ou wp_get_current_user() ne doit figurer dans les modèles rendus sur les routes statiques :

PHP
<?php // Do not do this on a static route. ?>
<?php if ( is_user_logged_in() ) : ?>
  <a href="/account/">Hi, <?php echo esc_html( wp_get_current_user()->display_name ); ?></a>
<?php else : ?>
  <a href="/login/">Sign in</a>
<?php endif; ?>

Deux solutions simples s’offrent à vous. Placez la route dans dynamicPaths si toute la page est personnalisée, par exemple un tableau de bord de compte. Ou gardez la page statique et affichez la partie personnalisée sous forme d’îlot de bloc dynamique, qui envoie un espace réservé compatible avec le cache dans le HTML stocké et récupère le véritable fragment dans la requête propre au visiteur :

PHP
<?php echo bs_block( array( 'name' => 'acme/greeting' ) ); ?>

Le guide Fragments personnalisés sur les pages en cache explique comment créer ce bloc.

Invalidation par signature ou par graphe

invalidate détermine l’expiration des documents stockés.

Aspect signature (par défaut) graph
Qui remplit le cache les absences de visiteurs anonymes et le préchauffeur votre étape de build, ainsi que les absences de visiteurs anonymes
Ce qui fait expirer les entrées TTL, enregistrements d’articles, modifications à l’échelle du site un nouveau build, le TTL étant une limite supérieure
Préchauffeur en arrière-plan disponible désactivé
Adapté aux sites classiques sites dotés d’un pipeline de déploiement

Le mode signature ne nécessite aucun outil. L’enregistrement d’un article purge ou préchauffe la page d’accueil et le permalien de cet article, et les changements à l’échelle du site, comme le changement de thème, font tourner l’identité du cache.

Le mode graph est destiné aux déploiements déterministes. Un build calcule un plan avec Static_Prerender_Runtime::build_plan(), rend uniquement les URL concernées, enregistre chaque résultat et active atomiquement l’ensemble final avec Static_Prerender_Early_Serve::install_artifact_entry(). Si la validation d’un document référencé échoue, l’ensemble précédent reste actif. Les routes mappées sont servies depuis l’artefact activé jusqu’à son remplacement par le build suivant ; le contenu modifié dans wp-admin n’apparaît donc sur ces routes qu’au déploiement suivant. Le préchauffeur par URL est désactivé dans ce mode, car les artefacts sont construits et activés comme un tout. Voici une configuration de production typique :

JSON
{
  "performance": {
    "profile": "speed",
    "staticPrerender": {
      "enabled": true,
      "invalidate": "graph",
      "ttl": 2592000,
      "earlyServe": true,
      "serveLoggedIn": true,
      "dynamicPaths": [
        "/account",
        "/cart",
        "/checkout",
        "/login",
        "/reset-password"
      ]
    }
  }
}

Le ttl de 30 jours limite uniquement l’ancienneté maximale d’un document servi. La fraîcheur vient du déploiement qui reconstruit le graphe. Le build API, le partitionnement et le transport de rendu interne sont détaillés dans la référence sur le pré-rendu statique.

Placer un CDN en amont

Le pré-rendu indique déjà quelles réponses peuvent être partagées : exactement celles qui portent un en-tête HIT. Laissez l’origine le convertir en en-tête de cache et demandez au CDN de suivre l’origine. Avec nginx devant PHP-FPM :

Nginx
map $upstream_http_x_blockstudio_static_prerender $edge_cache_control {
    "~^HIT"  "public, s-maxage=604800";
    default  "";
}

server {
    listen 80;
    server_name example.com;
    root /var/www/html;
    index index.php;

    location / {
        try_files $uri $uri/ /index.php?$args;
    }

    location ~ \.php$ {
        include fastcgi_params;
        fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name;
        fastcgi_pass unix:/run/php/php-fpm.sock;
        add_header Cache-Control $edge_cache_control;
    }
}

L’expression régulière correspond à HIT et à HIT-EARLY. Pour toute autre réponse, la variable est vide et nginx n’ajoute pas d’en-tête avec une valeur vide. Les absences dans le cache, les chemins dynamiques et les rendus pour les visiteurs connectés ne reçoivent donc aucune durée de cache partagé de la part de l’origine.

Côté CDN :

  • Ne mettez en cache HTML que lorsque l’origine envoie une durée de cache. Désactivez tout TTL de périphérie par défaut pour les réponses qui n’en ont pas.
  • Contournez le cache de périphérie pour les mêmes cookies que Blockstudio considère comme personnalisés (wordpress_logged_in_, wp-postpass_, comment_author_email_), ainsi que pour vos dynamicPaths, wp-admin et wp-json.
  • Purgez le CDN après chaque déploiement qui modifie des pages, des modèles ou des ressources. Le cache d’origine se renouvelle de lui-même ; le cache de périphérie ne sait pas qu’il doit le faire.

Si vous utilisez Tailwind avec "output": "link", la feuille de style URL est hachée selon son contenu ; ce chemin peut donc recevoir un en-tête de cache immuable à longue durée de vie.

Commandes de maintenance

Shell
wp bs prerender warm
wp bs prerender status
wp bs prerender purge
wp bs teardown

warm met en file les URL publiques obsolètes et en rend jusqu’à warm.concurrency par exécution, en affichant un récapitulatif JSON. purge supprime les documents stockés et la file du site actuel. teardown supprime les événements cron et l’état de service anticipé appartenant à cette installation, sans toucher aux fichiers de configuration.

Procédez dans cet ordre : commencez par le profil, puis activez le pré-rendu avec earlyServe désactivé, puis le service anticipé lorsque status et les en-têtes sont corrects. Chaque couche peut être annulée indépendamment en rétablissant sa valeur précédente.

Étapes suivantes