Quando lavori su un sito WordPress già online, soprattutto in fase di produzione o durante una fase di modifiche frequenti, può capitare una cosa abbastanza fastidiosa: tu aggiorni il sito, salvi il CSS, modifichi uno snippet, sistemi un JavaScript, ma il browser del visitatore continua a vedere una versione vecchia.
Il problema non è sempre WordPress. Spesso il browser ha semplicemente memorizzato una copia precedente della pagina, dei file CSS o dei file JavaScript. In pratica, per risparmiare tempo e velocizzare il caricamento, il browser dice: “Questa risorsa l’ho già vista, uso quella che ho in memoria”.
Questa cosa normalmente è positiva, perché rende il sito più veloce. Ma quando stai lavorando su un sito in produzione e vuoi essere sicuro che ogni visitatore veda sempre la versione aggiornata, può diventare un problema.
Una possibile soluzione è fare in modo che il sito sembri sempre “nuovo” agli occhi del browser. Tecnicamente si chiama cache busting, cioè una tecnica che serve a saltare la cache del browser aggiungendo una versione sempre diversa ai file caricati.
In questo tutorial vediamo come farlo in WordPress con uno snippet PHP, senza plugin aggiuntivi, usando un approccio adatto anche a siti costruiti con GeneratePress e GenerateBlocks.
Prima di tutto: cosa significa “saltare la cache del browser”
Quando una pagina carica un file CSS, ad esempio questo:
<link rel="stylesheet" href="https://www.tuosito.it/wp-content/themes/generatepress/style.css?ver=3.6.0">il browser può salvarlo nella sua cache locale.
Se poi lo stesso visitatore torna sul sito, il browser può decidere di non scaricare di nuovo quel file, perché pensa che sia già disponibile.
Ma se noi trasformiamo l’URL del file in qualcosa del genere:
<link rel="stylesheet" href="https://www.tuosito.it/wp-content/themes/generatepress/style.css?ver=sergio-482931">e al caricamento successivo diventa:
<link rel="stylesheet" href="https://www.tuosito.it/wp-content/themes/generatepress/style.css?ver=sergio-726194">per il browser quei due file sembrano due risorse diverse.
Anche se il file fisico è sempre lo stesso, l’URL cambia. Di conseguenza il browser è costretto a riscaricarlo.
Questo è il cuore del meccanismo.
Quando può essere utile questa tecnica
Una tecnica del genere può essere utile quando stai lavorando su un sito già online e vuoi evitare che il browser mostri versioni vecchie di:
- layout;
- CSS personalizzato;
- file JavaScript;
- modifiche al tema;
- modifiche inserite tramite Code Snippets;
- personalizzazioni di GeneratePress;
- blocchi o sezioni create con GenerateBlocks;
- elementi grafici che dipendono da CSS aggiornato;
- menu, header, footer o pop-up modificati da poco.
Per esempio, immaginiamo di aver modificato il CSS di una sezione hero realizzata con GenerateBlocks. Tu vedi tutto corretto in modalità anonima, ma un utente abituale del sito continua a vedere la vecchia spaziatura o il vecchio comportamento del bottone.
In quel caso il problema potrebbe essere proprio la cache del browser.
Attenzione: non è sempre una soluzione da tenere attiva per sempre
Prima di vedere il codice, è importante chiarire una cosa.
Forzare il browser a scaricare sempre CSS e JavaScript aggiornati significa anche impedirgli di sfruttare pienamente la cache.
Questo può avere un impatto sulle prestazioni, perché il visitatore scarica più spesso file che normalmente potrebbero essere riutilizzati.
Quindi questa tecnica ha senso soprattutto in alcuni casi:
- durante una fase di restyling;
- durante modifiche importanti al sito;
- quando hai problemi evidenti di cache lato browser;
- quando stai testando modifiche in produzione;
- quando vuoi essere sicuro che tutti vedano subito la versione aggiornata;
- per periodi temporanei;
- in casi particolari in cui il sito cambia spesso.
Su un sito stabile, invece, la cache è una tua alleata. Aiuta il sito a caricarsi più velocemente e riduce il lavoro del server.
La soluzione migliore, nella maggior parte dei casi, è usare questa tecnica con criterio.
Il codice completo
Ecco lo snippet PHP:
if ( ! defined( 'ABSPATH' ) ) {
exit;
}
/**
* 1. Evita che il browser usi una vecchia versione HTML della pagina.
*/
add_action( 'send_headers', 'sergio_no_cache_html_frontend', 0 );
function sergio_no_cache_html_frontend() {
if (
is_admin() ||
wp_doing_ajax() ||
wp_doing_cron() ||
( defined( 'REST_REQUEST' ) && REST_REQUEST )
) {
return;
}
if ( headers_sent() ) {
return;
}
header( 'Cache-Control: no-cache, must-revalidate, max-age=0' );
header( 'Pragma: no-cache' );
header( 'Expires: Wed, 11 Jan 1984 05:00:00 GMT' );
}
/**
* 2. Aggiunge una variabile random a CSS e JS locali.
*/
add_filter( 'style_loader_src', 'sergio_versione_random_asset_locali', 9999, 2 );
add_filter( 'script_loader_src', 'sergio_versione_random_asset_locali', 9999, 2 );
function sergio_versione_random_asset_locali( $src, $handle ) {
if ( is_admin() || empty( $src ) ) {
return $src;
}
$site_host = wp_parse_url( home_url(), PHP_URL_HOST );
$src_host = wp_parse_url( $src, PHP_URL_HOST );
/**
* Non tocca file esterni.
*/
if (
! empty( $src_host ) &&
! empty( $site_host ) &&
strtolower( $src_host ) !== strtolower( $site_host )
) {
return $src;
}
$asset_path = wp_parse_url( $src, PHP_URL_PATH );
if ( empty( $asset_path ) ) {
return $src;
}
/**
* Applica il random solo a CSS e JS.
*/
$is_css = '.css' === substr( $asset_path, -4 );
$is_js = '.js' === substr( $asset_path, -3 );
if ( ! $is_css && ! $is_js ) {
return $src;
}
/**
* Crea una versione random.
*/
$versione_random = 'sergio-' . wp_rand( 100000, 999999 );
/**
* Rimuove eventuale vecchio parametro ver.
*/
$src = remove_query_arg( 'ver', $src );
/**
* Aggiunge il nuovo parametro random.
*/
$src = add_query_arg( 'ver', $versione_random, $src );
return $src;
}Dove inserire questo codice in WordPress
Il modo più semplice è inserirlo tramite il plugin Code Snippets.
Il procedimento è questo:
- vai nella dashboard di WordPress;
- apri Snippet;
- crea un nuovo snippet PHP;
- incolla il codice;
- assegna un nome chiaro, ad esempio:
Forza aggiornamento cache browser CSS JS - imposta lo snippet per essere eseguito nel frontend;
- salva e attiva.
Non va inserito dentro una pagina, dentro un blocco HTML o dentro GenerateBlocks. È codice PHP e deve essere eseguito da WordPress.
Cosa fa questo snippet
Lo snippet lavora in due modi diversi.
La prima parte interviene sugli header HTTP della pagina HTML.
La seconda parte modifica gli URL dei file CSS e JavaScript locali.
Vediamole con calma.
1. Bloccare la cache HTML della pagina
La prima parte è questa:
add_action( 'send_headers', 'sergio_no_cache_html_frontend', 0 );Qui stiamo dicendo a WordPress:
Prima di inviare gli header della pagina al browser, esegui questa funzione.
La funzione è questa:
function sergio_no_cache_html_frontend() {Il suo scopo è comunicare al browser che la pagina HTML non deve essere considerata una copia “sempre valida”.
In particolare, questi header sono quelli più importanti:
header( 'Cache-Control: no-cache, must-revalidate, max-age=0' );
header( 'Pragma: no-cache' );
header( 'Expires: Wed, 11 Jan 1984 05:00:00 GMT' );Tradotto in modo semplice:
- Cache-Control: no-cache
dice al browser di non usare automaticamente una copia vecchia senza prima controllare; - must-revalidate
obbliga il browser a rivalidare la risorsa; - max-age=0
indica che la pagina scade immediatamente; - Pragma: no-cache
serve come compatibilità con sistemi più vecchi; - Expires nel passato
comunica che la risorsa è già scaduta.
In pratica, questa parte serve a ridurre il rischio che il browser mostri una vecchia versione HTML della pagina.
2. Evitare problemi in admin, AJAX, cron e REST API
Questa parte è molto importante:
if (
is_admin() ||
wp_doing_ajax() ||
wp_doing_cron() ||
( defined( 'REST_REQUEST' ) && REST_REQUEST )
) {
return;
}Qui stiamo dicendo: applica questa logica solo al frontend del sito.
Non vogliamo interferire con:
- area admin di WordPress;
- chiamate AJAX;
- cron di WordPress;
- REST API.
Questo è importante perché uno snippet troppo aggressivo potrebbe creare effetti collaterali nella dashboard, nei plugin o nelle chiamate tecniche di WordPress.
Quindi la funzione lavora solo dove ci interessa davvero: sulle pagine pubbliche del sito.
3. Controllare che gli header non siano già stati inviati
Questa parte:
if ( headers_sent() ) {
return;
}serve a evitare errori PHP.
Gli header HTTP possono essere inviati solo prima che WordPress abbia iniziato a stampare contenuto HTML. Se per qualche motivo gli header sono già partiti, provare a modificarli genererebbe un warning.
Quindi il codice controlla prima la situazione e, se non può più intervenire, si ferma.
La parte più importante: randomizzare CSS e JavaScript
La seconda parte dello snippet lavora qui:
add_filter( 'style_loader_src', 'sergio_versione_random_asset_locali', 9999, 2 );
add_filter( 'script_loader_src', 'sergio_versione_random_asset_locali', 9999, 2 );Questi due filtri di WordPress permettono di modificare gli URL dei file CSS e JavaScript caricati tramite il sistema standard di enqueue.
In pratica, WordPress carica un CSS così:
<link rel="stylesheet" href="https://www.tuosito.it/wp-content/themes/generatepress/style.css?ver=3.6.0">Lo snippet intercetta quell’URL e lo trasforma in qualcosa del genere:
<link rel="stylesheet" href="https://www.tuosito.it/wp-content/themes/generatepress/style.css?ver=sergio-842193">A ogni caricamento, il numero cambia.
Per il browser, quindi, il file sembra sempre diverso.
Perché viene usato il parametro ver
WordPress usa spesso il parametro ver per indicare la versione di un file.
Per esempio:
style.css?ver=6.8oppure:
frontend.js?ver=1.2.4Questo parametro non cambia il file fisico sul server, ma cambia l’URL con cui viene richiesto.
E per la cache del browser, l’URL è fondamentale.
Questi due URL vengono considerati diversi:
style.css?ver=1
style.css?ver=2Anche se puntano allo stesso file style.css.
Il nostro snippet sfrutta proprio questo comportamento.
Perché lo snippet rimuove il vecchio parametro ver
Questa parte:
$src = remove_query_arg( 'ver', $src );serve a pulire l’URL prima di aggiungere il nuovo parametro.
Se non lo facessimo, potremmo ritrovarci URL sporchi o duplicati.
Dopo la rimozione, viene aggiunto il nuovo parametro casuale:
$src = add_query_arg( 'ver', $versione_random, $src );Il risultato finale è un URL più pulito e controllato.
Perché lo snippet modifica solo file locali
Questa parte del codice è molto utile:
$site_host = wp_parse_url( home_url(), PHP_URL_HOST );
$src_host = wp_parse_url( $src, PHP_URL_HOST );Serve a capire se il file CSS o JavaScript appartiene al tuo sito oppure arriva da un dominio esterno.
Poi c’è questo controllo:
if (
! empty( $src_host ) &&
! empty( $site_host ) &&
strtolower( $src_host ) !== strtolower( $site_host )
) {
return $src;
}In pratica, se il file arriva da un dominio diverso, lo snippet non lo modifica.
Questo è giusto.
Per esempio, non vogliamo necessariamente modificare risorse esterne come:
https://fonts.googleapis.com/...
https://www.googletagmanager.com/...
https://cdn.jsdelivr.net/...Meglio lasciare intatti i file esterni, perché potrebbero avere logiche di cache proprie, CDN dedicate o sistemi di versionamento già ottimizzati.
Lo snippet interviene solo sui file locali del sito.
Perché controlla che siano davvero CSS o JS
Questa parte:
$is_css = '.css' === substr( $asset_path, -4 );
$is_js = '.js' === substr( $asset_path, -3 );
if ( ! $is_css && ! $is_js ) {
return $src;
}serve a evitare di modificare qualsiasi URL a caso.
Lo snippet lavora solo su file che finiscono con:
.cssoppure:
.jsQuindi non va a toccare immagini, font, documenti PDF o altre risorse.
È un controllo semplice, ma molto utile.
Esempio pratico
Prima dello snippet, una risorsa CSS potrebbe essere caricata così:
<link rel="stylesheet" href="https://www.sergiopinna.it/wp-content/themes/generatepress/style.css?ver=3.6.0">Dopo lo snippet, potrebbe diventare così:
<link rel="stylesheet" href="https://www.sergiopinna.it/wp-content/themes/generatepress/style.css?ver=sergio-518274">Al refresh successivo:
<link rel="stylesheet" href="https://www.sergiopinna.it/wp-content/themes/generatepress/style.css?ver=sergio-903621">E ancora:
<link rel="stylesheet" href="https://www.sergiopinna.it/wp-content/themes/generatepress/style.css?ver=sergio-147882">Il file è sempre lo stesso, ma per il browser l’indirizzo cambia sempre.
Quindi il browser non può dire: “Uso quello vecchio che ho già salvato”.
È costretto a fare una nuova richiesta.
Questa tecnica funziona anche con GeneratePress e GenerateBlocks?
Sì, funziona anche con siti realizzati con GeneratePress e GenerateBlocks, perché entrambi caricano molte risorse attraverso il sistema standard di WordPress.
Quindi lo snippet può intervenire su CSS e JS caricati correttamente tramite funzioni come:
wp_enqueue_style()
wp_enqueue_script()Questo significa che può funzionare con:
- CSS del tema;
- CSS del child theme;
- CSS generati da plugin;
- script locali;
- file di personalizzazione;
- asset caricati da GeneratePress;
- asset caricati da GenerateBlocks;
- file caricati da altri plugin, se locali.
Naturalmente dipende da come la singola risorsa viene caricata. Se un codice viene stampato direttamente inline nella pagina, cioè dentro un tag <style> o <script>, non avrà un URL da modificare.
E per il CSS inline?
Il CSS inline è diverso.
Un CSS inline è qualcosa del genere:
<style>
.mia-classe {
color: red;
}
</style>Oppure:
<style id="sergio-search-popover-css">
.sergio-search-popover {
position: fixed;
}
</style>In questo caso non esiste un file esterno tipo:
style.cssQuindi non c’è nessun parametro ver da modificare.
Il CSS inline viene stampato direttamente dentro l’HTML della pagina.
Per questo motivo, la parte dello snippet che blocca la cache HTML diventa importante: se il browser aggiorna l’HTML, aggiorna anche il CSS inline contenuto in quella pagina.
Differenza tra cache HTML e cache di CSS/JS
È importante distinguere due livelli:
Cache della pagina HTML
Riguarda la pagina vera e propria:
https://www.tuosito.it/pagina-esempio/Qui entrano in gioco gli header:
Cache-Control
Pragma
ExpiresCache degli asset
Riguarda file esterni come:
style.css
frontend.jsQui entra in gioco il parametro random:
?ver=sergio-123456Lo snippet lavora su entrambi i fronti:
- prova a evitare una vecchia versione HTML;
- forza CSS e JS locali a sembrare sempre nuovi.
Come verificare se funziona
Per controllare se lo snippet sta funzionando puoi fare così.
Apri una pagina del sito, poi fai clic destro e scegli:
Visualizza sorgente paginaCerca un file CSS o JS locale.
Prima potresti vedere qualcosa di simile:
style.css?ver=3.6.0Dopo l’attivazione dello snippet dovresti vedere qualcosa del genere:
style.css?ver=sergio-482915Poi aggiorna la pagina e controlla di nuovo.
Se il numero cambia, lo snippet sta funzionando.
Puoi anche usare gli strumenti sviluppatore del browser:
- apri Chrome;
- premi
F12; - vai nella tab Network;
- ricarica la pagina;
- osserva gli URL dei CSS e dei JS;
- controlla se il parametro
ver=sergio-...cambia.
Possibile svantaggio: il sito può caricare più risorse
Il vantaggio è chiaro: il browser vede sempre file aggiornati.
Lo svantaggio è altrettanto chiaro: il browser non può sfruttare la cache come farebbe normalmente.
Questo può influire su:
- velocità percepita;
- numero di richieste;
- consumo di banda;
- prestazioni su mobile;
- utenti con connessioni lente;
- PageSpeed Insights;
- Core Web Vitals.
Per un sito piccolo, magari l’impatto è minimo.
Per un sito più grande, con molti CSS, JS e plugin, può diventare più evidente.
Quindi il consiglio pratico è questo: questa tecnica è potentissima, ma va usata sapendo cosa si sta facendo.
Una versione più prudente: attivarla solo temporaneamente
Se vuoi una soluzione più “professionale”, puoi trasformare questa logica in una modalità temporanea.
Per esempio puoi definire una costante:
define( 'SERGIO_FORZA_NO_CACHE', true );e poi fare in modo che il codice venga eseguito solo quando questa costante è attiva.
Esempio:
if ( ! defined( 'ABSPATH' ) ) {
exit;
}
if ( ! defined( 'SERGIO_FORZA_NO_CACHE' ) || true !== SERGIO_FORZA_NO_CACHE ) {
return;
}In questo modo puoi accendere o spegnere facilmente la forzatura.
Quando stai lavorando sul sito, la imposti su:
trueQuando hai finito, la riporti a:
falseQuesta è una strada più pulita se non vuoi tenere la randomizzazione attiva tutto l’anno.
Una versione ancora più controllata: usare una versione manuale
Invece di generare una versione random a ogni caricamento, potresti usare una versione manuale.
Per esempio:
$versione_random = 'sergio-2026-05-03';Oppure:
$versione_random = 'sergio-v2';Così il browser scarica i nuovi file quando cambi tu la versione, ma poi può tornare a usare la cache.
È un approccio più equilibrato.
Esempio:
$versione_random = 'sergio-v1';Quando fai modifiche importanti:
$versione_random = 'sergio-v2';Poi:
$versione_random = 'sergio-v3';Questa logica è meno aggressiva rispetto al random continuo.
Random continuo o versione manuale?
Dipende dall’obiettivo.
Random continuo
È utile quando vuoi essere sicuro al 100% che ogni caricamento sembri nuovo.
Perfetto per:
- test;
- debug;
- modifiche frequenti;
- problemi di cache persistenti;
- restyling in corso;
- situazioni in cui devi vedere subito il risultato.
Però è meno performante.
Versione manuale
È più adatta a un sito stabile.
Perfetta per:
- produzione stabile;
- sito già pubblicato;
- buone performance;
- aggiornamenti controllati;
- minore consumo di risorse.
È meno aggressiva, ma più elegante.
Soluzione consigliata in produzione
Se il sito è in una fase di modifiche continue, puoi usare il random.
Se invece il sito è stabile e vuoi solo evitare problemi dopo gli aggiornamenti, meglio usare una versione manuale.
Per esempio, al posto di questo:
$versione_random = 'sergio-' . wp_rand( 100000, 999999 );puoi usare questo:
$versione_random = 'sergio-2026-05-03';Oppure:
$versione_random = 'sergio-v1';Così hai comunque un cache busting efficace, ma non costringi il browser a riscaricare tutto a ogni visita.
Codice alternativo con versione fissa
Ecco una versione più prudente dello snippet, pensata per un uso più stabile:
if ( ! defined( 'ABSPATH' ) ) {
exit;
}
/**
* Aggiunge una versione personalizzata a CSS e JS locali.
*/
add_filter( 'style_loader_src', 'sergio_versione_asset_locali', 9999, 2 );
add_filter( 'script_loader_src', 'sergio_versione_asset_locali', 9999, 2 );
function sergio_versione_asset_locali( $src, $handle ) {
if ( is_admin() || empty( $src ) ) {
return $src;
}
$site_host = wp_parse_url( home_url(), PHP_URL_HOST );
$src_host = wp_parse_url( $src, PHP_URL_HOST );
if (
! empty( $src_host ) &&
! empty( $site_host ) &&
strtolower( $src_host ) !== strtolower( $site_host )
) {
return $src;
}
$asset_path = wp_parse_url( $src, PHP_URL_PATH );
if ( empty( $asset_path ) ) {
return $src;
}
$is_css = '.css' === substr( $asset_path, -4 );
$is_js = '.js' === substr( $asset_path, -3 );
if ( ! $is_css && ! $is_js ) {
return $src;
}
/**
* Cambia questo valore quando vuoi forzare il browser
* a scaricare nuovamente CSS e JS.
*/
$versione_asset = 'sergio-v1';
$src = remove_query_arg( 'ver', $src );
$src = add_query_arg( 'ver', $versione_asset, $src );
return $src;
}Quando fai modifiche importanti, cambi semplicemente:
$versione_asset = 'sergio-v1';in:
$versione_asset = 'sergio-v2';Questo forza il browser a scaricare di nuovo i file, ma poi gli permette di rimetterli in cache.
Quale versione sceglierei?
Personalmente farei così.
Durante una fase di sviluppo, debug o restyling importante, userei la versione random:
$versione_random = 'sergio-' . wp_rand( 100000, 999999 );Quando il sito è stabile, passerei alla versione manuale:
$versione_asset = 'sergio-v1';Questo ti dà il meglio dei due mondi:
- durante i lavori vedi sempre tutto aggiornato;
- quando il sito è stabile non penalizzi troppo le prestazioni.
Attenzione ai plugin di cache e alla cache server
Questo snippet lavora principalmente lato WordPress e lato browser.
Ma in alcuni casi potresti avere anche altri livelli di cache, per esempio:
- cache del plugin;
- cache server;
- cache hosting;
- cache CDN;
- cache Cloudflare;
- cache del browser;
- cache generata da sistemi di ottimizzazione CSS/JS.
Se hai un plugin di cache attivo, lo snippet potrebbe non bastare da solo, perché la pagina HTML potrebbe essere servita già pronta dal sistema di cache prima ancora che WordPress riesca a generarla dinamicamente.
In quel caso dovresti anche svuotare:
- cache del plugin;
- cache del server;
- cache CDN;
- eventuale cache del browser.
Se invece non hai una cache pagina aggressiva, lo snippet può intervenire più facilmente.
Questo codice sostituisce un plugin di cache?
No.
Questo codice non è un plugin di ottimizzazione.
Fa quasi il contrario: evita che il browser si fidi troppo della cache.
Un plugin di cache serve a rendere il sito più veloce.
Questo snippet serve a evitare che il browser mostri versioni vecchie.
Sono due esigenze diverse.
In un sito in produzione stabile, di solito vuoi una buona cache.
In una fase di modifica, debug o aggiornamento, può essere utile forzare temporaneamente il refresh degli asset.
Quando non userei questa tecnica
Non la userei in modo permanente su siti molto grandi o molto trafficati.
Non la userei se il sito ha già ottime logiche di cache e versionamento.
Non la userei se il problema riguarda solo una piccola modifica CSS che può essere risolta cambiando manualmente la versione del file.
Non la userei per mascherare problemi più profondi di cache server, CDN o configurazioni errate.
La userei invece come strumento pratico e mirato quando voglio essere sicuro che il browser non continui a mostrare una versione vecchia.
Conclusione
Forzare il browser a vedere sempre una versione “nuova” del sito può essere molto utile quando stai lavorando su WordPress in produzione e vuoi evitare problemi legati alla cache.
Lo snippet visto in questo tutorial lavora su due livelli:
- impedisce al browser di fidarsi troppo della vecchia pagina HTML;
- aggiunge una versione random ai file CSS e JavaScript locali.
Il risultato è che il sito appare sempre aggiornato agli occhi del browser.
È una soluzione pratica, soprattutto durante modifiche continue, restyling, debug o interventi tecnici su layout, CSS e JavaScript.
Bisogna però usarla con criterio, perché saltare sempre la cache significa anche rinunciare a parte dei benefici prestazionali della cache stessa.
La soluzione ideale è usare il random quando stai lavorando attivamente sul sito, e poi passare a una versione manuale quando il sito torna stabile.
In questo modo hai controllo, pulizia e prestazioni migliori.
