Symptôme. Après une modification rapide du fichier theme.json pour ajouter une nouvelle taille de police à la palette typographique, l’éditeur de site du client s’est mis à afficher un écran presque vide, sans message d’erreur explicite, juste une interface tronquée où le panneau Styles refusait de s’ouvrir normalement. Aucune erreur PHP fatale, aucun message dans l’écran blanc habituel : simplement une interface qui semblait figée à mi-chargement.
Ce genre de panne silencieuse est particulièrement frustrant, car les journaux d’erreurs du serveur ne signalaient strictement rien d’anormal, laissant croire un instant à un problème plus profond côté hébergement ou plugin tiers.
Diagnostic : une erreur de syntaxe JSON, pas une erreur WordPress
Le fichier theme.json est un simple fichier JSON, sans tolérance aucune pour les erreurs de syntaxe : une virgule surnuméraire après le dernier élément d’un tableau, une virgule manquante entre deux propriétés, une accolade mal fermée, et c’est l’ensemble du fichier qui devient invalide. WordPress, dans ce cas précis, échoue silencieusement à parser le fichier, sans forcément produire d’erreur fatale visible, mais en appliquant des réglages par défaut incohérents avec ce qui était attendu à l’écran.
Dans ce cas précis, la nouvelle entrée ajoutée à la liste settings.typography.fontSizes manquait d’une virgule de séparation avec l’entrée précédente, une erreur d’inattention typique lors d’une modification rapide en fin de journée.
Méthode de validation locale avant tout déploiement
# Valider la syntaxe JSON directement en ligne de commande,
# sans dépendre de WordPress pour détecter l'erreur
cat theme.json | python3 -m json.tool > /dev/null
# En cas d'erreur, Python indique précisément la ligne et la colonne fautives
# Exemple de sortie : Expecting ',' delimiter: line 42 column 5 (char 1180)
Cette commande, exécutée en quelques secondes avant chaque déploiement, aurait immédiatement pointé la ligne quarante-deux comme fautive, bien avant que le fichier ne soit poussé sur l’environnement du client. Depuis cet incident, cette vérification fait partie intégrante de notre routine de déploiement pour tout projet reposant sur un thème bloc.
Prévention : intégrer la validation dans le flux de travail
- Configurer l’éditeur de code utilisé par l’équipe pour signaler visuellement toute erreur de syntaxe JSON en temps réel, un réglage disponible dans la plupart des éditeurs modernes.
- Ajouter une étape de validation automatique du fichier
theme.jsondans le script de déploiement du projet, pour bloquer toute mise en production d’un fichier invalide. - Conserver systématiquement une copie de sauvegarde du fichier précédent avant chaque modification, pour permettre un retour arrière immédiat en cas de panne constatée après déploiement.
Le schéma JSON officiel de WordPress, disponible publiquement et référencé dans de nombreux éditeurs de code via une simple annotation en tête de fichier, permet également une validation plus fine que la simple syntaxe, en signalant par exemple une propriété inconnue ou mal orthographiée dans la structure attendue.
Un cas voisin à ne pas confondre
Un theme.json syntaxiquement valide, mais contenant une propriété mal orthographiée ou une structure incorrecte, ne provoque généralement pas ce même écran figé : WordPress ignore simplement la propriété incomprise et poursuit son exécution normale, avec un résultat visuel simplement incohérent avec l’intention initiale. C’est uniquement l’invalidité syntaxique stricte du JSON qui provoque ce blocage plus sévère de l’interface.
Un fichier de configuration n’est jamais trop simple pour mériter une validation automatique avant chaque déploiement. C’est justement sa simplicité apparente qui rend l’erreur d’inattention si facile à commettre.
En résumé
Cette panne, résolue en quelques minutes une fois la bonne méthode appliquée, a coûté près d’une heure de recherche avant que la piste JSON ne soit sérieusement envisagée. Intégrer une validation systématique et automatisée avant tout déploiement reste, à ce jour, la meilleure prévention contre ce genre d’incident qui semble anodin mais qui peut bloquer l’ensemble d’un site en quelques secondes.
