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:
- 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. - 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 includeX-Blockstudio-Static-Prerender: HIT. - 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:
{
"$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.enabledregistra 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 predefinito86400).dynamicPathselenca i prefissi di percorso che devono sempre essere elaborati in tempo reale.warmpianifica un processo in background che aggiorna le URL pubbliche non più recenti ogniintervalsecondi.
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_*ocomment_author_email_*, a meno cheserveLoggedInnon 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:
<!-- 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:
wp bs prerender status
{
"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:
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_CACHEche non gli appartiene. Se un altro plugin di caching possiede giàadvanced-cache.php, la risposta anticipata resta disattivata. - Se
WP_CACHEè già definito cometrue,wp-config.phpviene lasciato invariato. Sugli host in cuiwp-config.phpnon è 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,Linkper impostazione predefinita, vengono memorizzate con ogni documento e inviate di nuovo a ogni hit, così un’intestazioneLinkinviata da una pagina conheader()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 // 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 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:
{
"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:
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 vostridynamicPaths,wp-adminewp-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
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
- Riferimento sul prerendering statico: compilazioni del grafo, attivazione degli artefatti, conservazione e hook di osservabilità.
- Prestazioni: cosa modifica il profilo
speede come misurare l’effetto. - Memorizzazione nella cache: la directory della cache in cui risiede ogni documento archiviato.
- Frammenti personalizzati nelle pagine memorizzate nella cache: contenuti specifici per visitatore nei percorsi statici.
- Come distribuire un sito Blockstudio: come integrare la sincronizzazione, lo svuotamento della cache e il preriscaldamento delle pagine in una release.