« Failed to load block » après un changement d’outil d’intégration continue

« Failed to load block: monsite/bloc-galerie-avancee. This block has been added from a third party plugin. » Le message s’affichait dans l’éditeur, sur un bloc pourtant présent en production depuis des mois, sans qu’aucune ligne de son code n’ait été touchée récemment.

Symptôme

Le bloc disparaissait purement et simplement du rendu de l’éditeur, remplacé par un message d’avertissement générique. Côté front, rien ne s’affichait à l’emplacement du bloc, sans erreur PHP visible dans les journaux du serveur. La console du navigateur, elle, montrait une requête réseau en échec avec un code 404 sur un fichier index.js.

La particularité de ce cas : le code source du bloc n’avait pas changé depuis plusieurs semaines. Seule une chose avait bougé récemment dans le projet : l’équipe venait de migrer sa chaîne d’intégration continue vers un nouvel outil, avec un pipeline de construction reconfiguré de zéro.

Diagnostic

Le fichier block.json du bloc référence ses scripts par chemin relatif :

{
  "name": "monsite/bloc-galerie-avancee",
  "editorScript": "file:./build/index.js",
  "viewScript": "file:./build/view.js"
}

L’ancienne configuration de build produisait ses fichiers dans un dossier build/, à la racine du bloc. Le nouvel outil d’intégration continue, configuré par une autre personne de l’équipe sans connaissance fine de la structure attendue par WordPress, avait redirigé la sortie vers un dossier dist/, jugé plus conventionnel dans d’autres écosystèmes JavaScript.

Trois caractères de différence entre build et dist, mais un chemin déclaré dans block.json qui continuait à pointer vers un dossier qui n’existait tout simplement plus après le déploiement :

ls -la wp-content/plugins/monsite-blocs/bloc-galerie-avancee/
# build/  -> absent
# dist/   -> présent, mais non référencé par block.json

Correctif

Deux options se présentaient : renommer le dossier de sortie du nouveau pipeline pour revenir à build/, ou mettre à jour block.json pour qu’il pointe vers dist/. La première option a été retenue, pour rester alignée avec les conventions déjà utilisées sur les autres blocs du même projet :

# Ancienne configuration du nouvel outil de CI
output:
  path: "dist"

# Configuration corrigée
output:
  path: "build"

Après correction et relance du pipeline, la commande wp plugin list puis un simple rechargement de l’éditeur ont suffi à confirmer que le bloc rechargeait correctement ses scripts, sans autre modification de code.

Vérifier le chemin publié, pas seulement le code source

La vérification a posteriori la plus utile n’a pas porté sur le code JavaScript du bloc, mais sur le contenu réellement déployé sur le serveur, via une simple commande listant les fichiers présents dans le dossier du plugin après déploiement :

find wp-content/plugins/monsite-blocs -maxdepth 2 -type d

Prévention

• Ajouter une étape de vérification dans le pipeline qui échoue explicitement si le chemin attendu par block.json n’existe pas après le build ;
• Documenter, dans le dépôt du projet, la convention de nommage attendue pour le dossier de sortie, plutôt que de la laisser implicite dans la tête d’une seule personne ;
• Tester le déploiement sur un environnement de recette avant toute migration d’outil d’intégration continue, en particulier pour les projets qui embarquent des blocs personnalisés avec build JavaScript.
• Conserver, dans la documentation interne du projet, un exemple concret de chemin attendu par chaque block.json, pour qu’une nouvelle personne rejoignant l’équipe ne redécouvre pas cette convention par erreur.

Un autre réflexe utile consiste à comparer, avant et après chaque changement de pipeline, la liste des fichiers réellement publiés sur le serveur avec celle attendue par les déclarations de blocs du projet. Un script simple, exécuté juste après le déploiement, peut confronter automatiquement ces deux listes et faire échouer la publication si un chemin déclaré ne correspond à aucun fichier existant, plutôt que de laisser l’éditeur afficher un message d’avertissement générique une fois le déploiement terminé.

Un changement d’outil de construction ne touche jamais que « la tuyauterie » en apparence ; pour un bloc Gutenberg, cette tuyauterie fait pourtant partie du contrat que WordPress attend.

En résumé

Un message « Failed to load block » ne signale pas toujours une erreur dans le code du bloc lui-même : il peut simplement indiquer que le fichier attendu ne se trouve plus là où block.json le déclare. Une migration d’outil d’intégration continue est un moment à risque précis pour ce genre de régression silencieuse, d’autant qu’elle ne remonte aucune erreur PHP côté serveur.