« Loading chunk failed » : un script de bloc asynchrone échoue après déploiement

« Loading chunk failed » ou son équivalent « Failed to fetch dynamically imported module » : ce message apparaît dans la console juste après une mise en production, sur un bloc dont le script principal se charge normalement, mais dont une partie du code, découpée en module séparé, ne se trouve plus à l’endroit attendu. Ce billet ne traite pas des erreurs de build elles-mêmes, mais uniquement de ce qui se passe une fois le déploiement effectué.

Le scénario classique : un onglet resté ouvert depuis avant le déploiement tente de charger dynamiquement un fragment de script, par exemple via import() à l’intérieur d’un bloc qui découpe son code pour n’en charger qu’une partie à la demande. Le fichier référencé par le navigateur porte un nom haché qui n’existe plus sur le serveur, remplacé par une nouvelle version au hachage différent.

Symptôme : une erreur qui ne touche que certains visiteurs

Ce qui rend ce bug difficile à percevoir, c’est qu’il ne touche pas tout le monde en même temps. Un visiteur qui charge la page après le déploiement récupère la bonne version du script, avec les bonnes références de fichiers. Un visiteur dont l’onglet était déjà ouvert avant le déploiement, ou dont le navigateur a mis en cache l’ancienne page HTML, continue de référencer les anciens noms de fichiers, désormais absents du serveur.

Sur le plan technique, le module concerné est le plus souvent chargé via viewScriptModule dans block.json, une fonctionnalité disponible depuis WordPress 6.5, ou via un import() dynamique à l’intérieur d’un module déjà chargé de cette façon.

Diagnostic : comparer les noms de fichiers avant et après

La vérification la plus directe consiste à ouvrir l’onglet réseau des outils de développement au moment où l’erreur se produit, et à noter le nom exact du fichier introuvable. Ce nom contient généralement un hachage de contenu généré par l’outil de build, du type view-a1b2c3.js. Il suffit ensuite de comparer ce nom à celui présent dans le dossier de build actuellement déployé sur le serveur.

$ ls build/ | grep view-
view-d4e5f6.js

Si le fichier référencé par l’erreur (view-a1b2c3.js) diffère du fichier réellement présent (view-d4e5f6.js), la cause est confirmée : le navigateur travaille avec une version de page antérieure au déploiement, qui pointe vers des fichiers disparus.

Correctif immédiat : forcer un rechargement propre

Le correctif côté visiteur reste simple, à condition de le déclencher automatiquement plutôt que d’attendre que l’utilisateur comprenne le problème par lui-même. Une gestion d’erreur autour de l’import dynamique permet de détecter l’échec et de proposer un rechargement de la page :

try {
	const module = await import( './fragments/panneau-avance.js' );
	module.initialiser();
} catch ( erreur ) {
	if ( erreur.message.includes( 'Failed to fetch dynamically imported module' ) ) {
		window.location.reload();
	}
}

Correctif structurel : garder les anciens fichiers un moment

La solution la plus robuste ne se joue pas côté script, mais côté déploiement : conserver les fichiers de l’ancienne version pendant une fenêtre de quelques heures après la mise en production, le temps que les onglets déjà ouverts se rafraîchissent naturellement, plutôt que de supprimer immédiatement l’ancien dossier de build.

Prévention : un identifiant de version stable côté cache

Sur les projets qui déploient fréquemment, ajouter un identifiant de version explicite à l’enqueue du script, via le dernier paramètre de wp_enqueue_script, aide à distinguer clairement les versions dans les journaux serveur et facilite le diagnostic en cas d’incident récurrent.

• Ne jamais supprimer immédiatement l’ancien dossier de build après un déploiement.
• Ajouter une gestion d’erreur explicite autour de chaque import() dynamique dans les blocs qui en utilisent.
• Documenter la fenêtre de conservation des anciens fichiers dans la procédure de déploiement de l’équipe.

En résumé

Une erreur de chargement de module après déploiement se diagnostique en comparant le nom de fichier réclamé par le navigateur à celui réellement présent sur le serveur, et se corrige en deux temps : une gestion d’erreur qui recharge la page côté client, et une politique de conservation temporaire des anciens fichiers côté déploiement. Ce n’est pas un bug du bloc lui-même, mais un effet de bord du découpage de code combiné à un déploiement trop brutal.