Gli stili del tema child di WordPress non si caricano

Il file style.css del tuo tema child non si carica perché WordPress non lo mette in coda al posto tuo. Il foglio di stile del tema child va registrato a mano nel functions.php del tema child, e quell’enqueue ha quasi sempre uno di due difetti: o non c’è proprio, oppure viene caricato senza dichiarare il foglio di stile del tema parent come dipendenza, così le tue regole finiscono nel punto sbagliato della cascade e vengono sovrascritte. Sistema l’enqueue e gli stili tornano. Il vecchio trucco dell’@import che probabilmente hai copiato da un tutorial del 2013 è la soluzione sbagliata.

Perché succede

Un tema child classico è fatto di due file obbligatori: un style.css con un blocco header che indica il parent, e un functions.php. La riga Template: dell’header dice a WordPress da quale parent ereditare i template. È l’unica cosa che WordPress fa in automatico. Legge l’header, imposta il fallback dei template, e si ferma. Non mette mai in coda il tuo style.css del child sul front end.

Il tema parent, intanto, mette in coda il suo foglio di stile dal suo functions.php, agganciato a wp_enqueue_scripts. Il functions.php del tuo child gira per primo, poi quello del parent, poi si attiva tutto ciò che è su quell’hook. Se il tuo child non chiama mai wp_enqueue_style per il proprio file, il browser non lo richiede mai. La pagina sembra il tema parent grezzo perché è esattamente quello che è.

Il secondo tipo di errore è più sottile. Metti in coda il foglio di stile del child, si carica, ma le tue sovrascritture non fanno niente. È un problema di ordine di caricamento. Quando due regole hanno la stessa specificità, vince quella che si carica per ultima. Se il CSS del tuo child si carica prima di quello del parent, il parent vince ogni pareggio. L’array delle dipendenze su wp_enqueue_style è ciò che forza l’ordine.

Un’altra cosa che la gente sbaglia: get_template_directory_uri() punta alla cartella del tema parent, mentre get_stylesheet_directory_uri() punta alla cartella del tema attivo (il child). Se le scambi, metti in coda il style.css del parent una seconda volta e non tocchi mai quello del child.

La soluzione, in ordine

Per prima cosa, verifica cosa si sta effettivamente caricando. Apri la pagina che non funziona, visualizza il sorgente e cerca il nome della cartella del tuo tema child. WordPress renderizza gli stili in coda come <link id="handle-css" href="..."> — l’id è il tuo handle più -css. Se il style.css del tuo child non è affatto nel <head>, l’enqueue non sta girando. Se c’è ma gli stili non si applicano, è un problema di dipendenza/ordine. Questo singolo controllo ti dice quale dei due difetti hai.

Secondo, trova il vero handle del parent. La maggior parte dei temi moderni (Astra, GeneratePress, i temi Twenty-*) mette già in coda il proprio foglio di stile sotto un handle specifico — astra-theme-css, generate-style-css, twenty-twenty-four-style, e così via. Ti serve quella stringa esatta. Fai un grep sul tema parent, oppure leggila dal <link id="...-css"> nel sorgente della pagina (togli il -css finale).

Terzo, scrivi l’enqueue. Nel caso comune in cui il parent carica già il proprio foglio di stile, non rimetti in coda il parent. Metti in coda solo il child, ed elenchi l’handle del parent come dipendenza in modo che il tuo si carichi dopo:

<?php
add_action( 'wp_enqueue_scripts', 'child_enqueue_styles', 20 );

function child_enqueue_styles() {
    wp_enqueue_style(
        'child-style',
        get_stylesheet_directory_uri() . '/style.css',
        array( 'astra-theme-css' ), // <-- the parent's REAL handle
        wp_get_theme()->get( 'Version' )
    );
}

Se il tema parent non mette in coda il proprio foglio di stile (alcuni temi più vecchi o minimali si affidano all’@import), allora metti in coda entrambi, e fai dipendere il child dal parent:

<?php
add_action( 'wp_enqueue_scripts', 'child_enqueue_styles' );

function child_enqueue_styles() {
    wp_enqueue_style(
        'parent-style',
        get_template_directory_uri() . '/style.css'
    );
    wp_enqueue_style(
        'child-style',
        get_stylesheet_directory_uri() . '/style.css',
        array( 'parent-style' ),
        wp_get_theme()->get( 'Version' )
    );
}

L’argomento wp_get_theme()->get('Version') è il tuo cache-buster. Incrementa la riga Version: nell’header dello style.css del child e i browser riscaricano il file. Salta questo passaggio e ti ritroverai a modificare il CSS giurando che non cambia niente, quando in realtà è solo in cache.

Se il functions.php ha un errore di sintassi, l’intero file muore in silenzio e nessuno dei tuoi enqueue gira — il che si presenta esattamente come “gli stili non si caricano”. Attiva WP_DEBUG, oppure incolla il tuo debug.log nel nostro decodificatore di log errori WordPress per individuare in fretta l’errore critico.

Cosa non fare

Non usare l’@import. Il consiglio dell’era del Codex era di mettere @import url("../parenttheme/style.css"); in cima allo style.css del child. Funziona, ma è lento — il browser non può iniziare a scaricare il CSS del parent finché non ha analizzato il CSS del child, quindi le due richieste vanno in serie invece che in parallelo. L’handbook ufficiale di WordPress lo sconsiglia da anni. Se il tuo tutorial ti ha detto di fare così, quel tutorial è il motivo per cui i tuoi stili sono a pezzi.

Non scrivere a mano l’handle 'parent-style' mettendo in coda il file del parent alla cieca. Il famoso snippet del Codex fa esattamente questo, ed è sbagliato per qualsiasi tema che registra già il proprio foglio di stile sotto un handle diverso. Finisci per caricare il CSS del parent due volte e la tua dipendenza punta a un handle che potrebbe non esistere.

Non chiamare wp_enqueue_style al livello superiore del functions.php. Deve girare dentro una funzione agganciata a wp_enqueue_scripts. Chiamata troppo presto, non fa niente.

Non copiare l’intero functions.php del parent dentro il child. Si caricano entrambi; quello del child gira per primo. Copiarlo causa dichiarazioni di funzioni duplicate e un errore critico.

Un’avvertenza: tutto questo riguarda i temi classici (con template PHP). Se il tuo parent è un block theme, lo stile passa perlopiù attraverso theme.json e il Site Editor, e le sovrascritture di style.css si comportano in modo diverso — in quel caso mi fiderei di meno e verificherei direttamente, invece di dare per scontato che questo enqueue sia la soluzione.

Ancora bloccato?

Verifica che la riga Template: dell’header dello style.css del child corrisponda esattamente al nome della cartella del parent, rispettando maiuscole e minuscole — non il nome visualizzato del parent. Poi ricontrolla il sorgente della pagina: handle presente, caricamento dopo il parent, query string della versione incrementata. Se il <link> c’è, si carica per ultimo, e il CSS ancora non si applica, non è più un problema di enqueue — è di specificità, e la soluzione si sposta dentro le regole stesse.