Vai al contenuto

Servire WordPress come HTML statici

La maggior parte delle pagine di un sito aziendale o di documentazione è uguale per tutti i visitatori anonimi. WordPress si avvia comunque, carica ogni plugin, esegue il tema e visualizza i blocchi a ogni richiesta. Un plugin per la cache delle pagine può essere utile, ma aggiunge un altro componente con regole proprie su cosa sia sicuro memorizzare.

Blockstudio include una funzione di prerendering statico facoltativa. Memorizza documenti HTML anonimi completi in una propria directory di cache e, se lo consentite, li serve da un drop-in advanced-cache.php prima che si avvii WordPress. Tutto si configura in blockstudio.json.

Questa guida attiva la funzione passo dopo passo, mostra come verificare cosa viene memorizzato nella cache e cosa no, spiega l’unica regola che protegge i visitatori che hanno effettuato l’accesso e termina con una configurazione CDN che memorizza nella cache solo ciò che l’origine indica come idoneo.

Come viene gestita una richiesta

Con il prerendering attivo, una richiesta idonea può concludersi in uno di tre modi:

  1. Risposta immediata dalla cache. Il drop-in trova un documento salvato nella mappa delle route e lo trasmette prima che venga caricato WordPress. La risposta include X-Blockstudio-Static-Prerender: HIT-EARLY.
  2. Cache hit. WordPress si avvia e, in corrispondenza di template_redirect, Blockstudio trova un documento salvato ancora valido e lo invia al posto di visualizzare il template. La risposta include X-Blockstudio-Static-Prerender: HIT.
  3. Cache miss. WordPress visualizza normalmente la pagina. Se il visitatore è anonimo e il risultato è un documento HTML completo con stato 200, Blockstudio lo salva per la richiesta successiva.

Le richieste non idonee non accedono mai alla cache.

Passaggio 1: attivare il profilo e la cache

Iniziate con il profilo delle prestazioni e il prerendering, lasciando disattivata la distribuzione anticipata:

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
      }
    }
  }
}

A cosa serve ogni elemento:

  • profile: "speed" attiva le impostazioni predefinite di produzione per il frontend: rimuove il rumore nell’head, il rilevamento oEmbed, XML-RPC e le risorse generiche del frontend di core, e precarica i link della stessa origine su richiesta. La rimozione delle risorse del frontend di core è l’impostazione da verificare per prima, perché una pagina che ne dipende si rompe in modo evidente. Qualsiasi valore figlio prevale sul profilo.
  • staticPrerender.enabled registra il runtime. Quando è false, la funzione non scrive file né registra hook di richiesta.
  • ttl è l’età massima, in secondi, di un documento salvato (valore predefinito 86400).
  • dynamicPaths elenca i prefissi di percorso che devono sempre essere elaborati in tempo reale.
  • warm pianifica un processo in background che aggiorna le URL pubbliche non più recenti ogni interval secondi.

La riga $schema copre tutte le chiavi, quindi un editor con supporto per lo schema JSON segnala un errore come "ttl": 0 (il minimo è 1).

Passaggio 2: sapere quali richieste sono idonee

Blockstudio è prudente su ciò che memorizza. Queste richieste escludono sempre la cache:

  • tutto ciò che non è GET
  • qualsiasi URL con una stringa di query
  • wp-admin, wp-json, wp-login.php, xmlrpc.php, Ajax e cron
  • feed, ricerca e percorsi di anteprima
  • richieste con un’intestazione X-WP-Nonce
  • percorsi in dynamicPaths
  • visitatori con un cookie wordpress_logged_in_*, wp-postpass_* o comment_author_email_*, a meno che serveLoggedIn non sia attivo

I percorsi dinamici vengono confrontati rispettando i confini dei percorsi. Con la configurazione precedente:

Richiesta Esclusa
/pricing/ no
/account/orders/ sì
/accounting/ no
/checkout sì
/pricing/?utm_source=x sì
/blog/feed/ sì

Per essere salvato, il risultato deve essere un documento completo: la risposta deve iniziare con <!doctype html o <html, avere stato 200 e non contenere il marcatore di esclusione. Un template che non deve mai essere salvato può stampare il marcatore in qualsiasi punto della pagina:

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

Le pagine di errore non vengono mai salvate, quindi un 404 con il tema applicato non potrà mai essere riproposto come risposta riuscita.

Passaggio 3: verificare le risposte dalla cache

Visitate alcune pagine in una finestra privata, poi chiedete a Blockstudio cosa contiene:

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": []
}

Le dimensioni di files e bytes aumentano man mano che vengono salvati i documenti; queue mostra il lavoro arretrato del processo di aggiornamento e diagnostics contiene i contatori di cache hit, cache miss, build ed errori per ambito. Per controllare una singola pagina, richiedetela due volte come visitatori anonimi e cercate l’intestazione:

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

La seconda risposta include X-Blockstudio-Static-Prerender: HIT. Usate un GET come sopra: curl -I invia una richiesta HEAD, che esclude sempre la cache.

Passaggio 4: servire prima dell’avvio di WordPress

Quando le risposte dalla cache sono corrette, impostate "earlyServe": true. Blockstudio gestisce quindi tre piccoli elementi di stato: un drop-in wp-content/advanced-cache.php, una mappa condivisa delle route wp-content/blockstudio-static-prerender-map.php e una dichiarazione WP_CACHE in wp-config.php. Vengono installati alla successiva richiesta di amministrazione.

Alcune regole garantiscono la sicurezza su hosting condiviso e multisito:

  • Blockstudio non sovrascrive mai un drop-in, una mappa o una riga WP_CACHE che non gli appartiene. Se un altro plugin di caching possiede già advanced-cache.php, la risposta anticipata resta disattivata.
  • Se WP_CACHE è già definito come true, wp-config.php viene lasciato invariato. Sugli host in cui wp-config.php non è scrivibile, definitelo voi.
  • Prima di servire, sia il drop-in sia il percorso PHP verificano che il foglio di stile Tailwind con hash del contenuto, collegato al documento, esista ancora. Se non esiste, la richiesta viene inoltrata a WordPress invece di essere servita senza stili.
  • Le voci multisito condividono una mappa, ma sono isolate per host, percorso home e ID del sito.
  • Le intestazioni di risposta indicate in replayHeaders, Link per impostazione predefinita, vengono memorizzate con ogni documento e inviate di nuovo a ogni hit, così un’intestazione Link inviata da una pagina con header() resta disponibile durante la risposta anticipata. Le intestazioni di cookie e cache non vengono mai riprodotte.

Le richieste servite in anticipo includono X-Blockstudio-Static-Prerender: HIT-EARLY. Disattivando earlyServe o enabled, lo stato di cui Blockstudio è responsabile viene rimosso una volta, mentre wp bs teardown lo rimuove esplicitamente nelle installazioni Composer che non dispongono di un hook di disattivazione.

Visitatori con sessione attiva e markup identico

Per impostazione predefinita, i visitatori con sessione attiva ricevono sempre una pagina generata al momento. L’impostazione "serveLoggedIn": true consente loro di usare anche un documento già archiviato, rendendo il sito altrettanto veloce per editor e clienti quanto per i visitatori anonimi.

Le risposte personalizzate non creano mai voci nella cache: se manca una pagina per un utente con sessione attiva, viene generata al momento e non archiviata. È facile sottovalutare la conseguenza. Con serveLoggedIn attivo, un visitatore con sessione attiva riceve il documento anonimo, se disponibile, e una pagina personalizzata generata al momento solo se non esiste. Qualsiasi diramazione del template basata sull’utente corrente viene eseguita solo quando manca una pagina; di conseguenza la stessa pagina cambia tra una visita e l’altra e la diramazione personalizzata di fatto non viene mai usata nei percorsi memorizzati nella cache.

La regola che ne deriva: in ogni percorso al di fuori di dynamicPaths, il markup per gli utenti con sessione attiva deve essere identico byte per byte a quello anonimo. Ciò significa che nei template che vengono generati nei percorsi statici non devono esserci diramazioni is_user_logged_in() o wp_get_current_user():

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; ?>

Ci sono due soluzioni semplici. Spostate il percorso in dynamicPaths quando l’intera pagina è personalizzata, ad esempio in una dashboard dell’account. Oppure mantenete la pagina statica e generate la parte personale come blocco dinamico, che inserisce nel documento archiviato in HTML un segnaposto sicuro per la cache e recupera il frammento effettivo nella richiesta del visitatore:

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

La guida Frammenti personalizzati nelle pagine memorizzate nella cache spiega come creare questo blocco.

Invalidazione tramite firma o grafo

invalidate determina quando scadono i documenti archiviati.

Aspetto signature (predefinita) graph
Chi popola la cache richieste anonime senza corrispondenza e il processo di preriscaldamento il passaggio di compilazione, oltre alle richieste anonime senza corrispondenza
Cosa fa scadere le voci TTL, salvataggi degli articoli, modifiche a livello di sito una nuova compilazione, con TTL come limite massimo
Processo di preriscaldamento in background disponibile disattivato
Adatta a siti comuni siti con pipeline di distribuzione

La modalità signature non richiede strumenti. Quando salvate un articolo, la home page e il permalink dell’articolo vengono svuotati dalla cache o precaricati nuovamente; le modifiche a livello di sito, come il cambio di tema, aggiornano l’identificativo della cache.

La modalità graph è pensata per distribuzioni deterministiche. Durante la compilazione viene calcolato un piano con Static_Prerender_Runtime::build_plan(), vengono generate solo le URL interessate, viene registrato ogni risultato e il set completo viene attivato atomicamente con Static_Prerender_Early_Serve::install_artifact_entry(). Se la convalida di un documento referenziato non riesce, resta attivo il set precedente. I percorsi mappati vengono serviti dall’artefatto attivato fino alla compilazione successiva, che lo sostituisce; pertanto, i contenuti modificati in wp-admin raggiungono quei percorsi con la distribuzione successiva. In questa modalità il processo di preriscaldamento per URL è disattivato, perché gli artefatti vengono compilati e attivati come un’unica unità. Una tipica configurazione di produzione è la seguente:

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

I 30 giorni di ttl indicano solo l’età massima che può avere un documento servito. L’aggiornamento dipende dalla distribuzione che ricompila il grafo. La compilazione API, lo sharding e il trasporto di rendering interno sono descritti nella guida al prerendering statico.

Anteporre un CDN

Il prerendering indica già quali risposte possono essere condivise: solo quelle che includono un’intestazione HIT. Fate in modo che l’origine la trasformi in un’intestazione di cache e che CDN segua le indicazioni dell’origine. Con nginx davanti a 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’espressione regolare corrisponde sia a HIT sia a HIT-EARLY. Per tutte le altre risposte, la variabile è vuota e nginx non aggiunge un’intestazione con valore vuoto; quindi le richieste senza corrispondenza, i percorsi dinamici e le richieste degli utenti con sessione attiva non ottengono dall’origine un tempo di permanenza nella cache condivisa.

Sul lato di CDN:

  • Memorizzate HTML nella cache solo quando l’origine invia un tempo di permanenza. Disattivate qualsiasi TTL predefinito per le risposte che ne sono prive.
  • Escludete dalla cache edge gli stessi cookie che Blockstudio considera personali (wordpress_logged_in_, wp-postpass_, comment_author_email_) e i vostri dynamicPaths, wp-admin e wp-json.
  • Svuotate CDN dopo ogni distribuzione che modifica pagine, template o risorse. La cache dell’origine si aggiorna da sola; la cache edge non sa che deve farlo.

Se usate Tailwind con "output": "link", il foglio di stile URL ha un hash basato sul contenuto, quindi il percorso può essere servito con un’intestazione di cache immutabile a lunga durata.

Comandi di manutenzione

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

warm inserisce nella coda gli URL pubblici non aggiornati e ne genera fino a warm.concurrency per esecuzione, stampando un riepilogo JSON. purge rimuove i documenti archiviati e la coda del sito corrente. teardown rimuove gli eventi cron e lo stato di distribuzione anticipata gestiti da questa installazione, lasciando invariati i file di configurazione.

Procedete in questo ordine: prima il profilo, poi il prerendering con earlyServe disattivato e infine la distribuzione anticipata, una volta verificati status e le intestazioni. Ogni livello può essere ripristinato autonomamente rimettendo il valore precedente.

Passaggi successivi