Le fichier servi au navigateur n'est plus celui que vous avez écrit : il a été traduit par une étape de Transpilation, assemblé et compressé. Le jour où une erreur remonte, elle désigne la ligne 1 colonne 48213 d'un fichier illisible.
Une source map rétablit le lien entre ces deux mondes.
Définition
Une source map est un fichier qui associe chaque position du code généré à la position correspondante dans le code source d'origine. Les outils de développement la chargent automatiquement et affichent vos fichiers d'origine à la place du fichier réellement exécuté.
// Dernière ligne du fichier produit
//# sourceMappingURL=bundle.js.map
// bundle.js.map, en simplifié
{
"version": 3,
"file": "bundle.js",
"sources": ["../src/panier.js", "../src/outils.js"],
"names": ["totalPanier", "remise"],
"mappings": "AAAA,SAASA,YAAT,CAAsBC,MAAtB..."
}Le champ mappings contient les correspondances dans un format compact, illisible à l'oeil nu mais très compressible. Un champ sourcesContent facultatif embarque en plus le texte des fichiers d'origine, ce qui rend la carte autonome.
Comment l'activer
Chaque outil expose un réglage : build.sourcemap chez Vite, devtool chez Webpack, une option en ligne de commande pour un compilateur. Le choix se fait entre précision et vitesse de génération.
En développement, une carte approximative mais rapide suffit largement. Pour la production, mieux vaut une carte complète, qui sera de toute façon consultée rarement, mais dans un moment où chaque indice compte.
Un service de suivi d'erreurs accepte de recevoir les cartes séparément, au moment du déploiement. Les piles d'appels remontées deviennent lisibles pour l'équipe, sans que les fichiers soient accessibles publiquement.
Faut-il les publier ?
Une source map livrée en ligne expose votre code source d'origine, commentaires compris, à qui ouvre les outils de développement. Ce n'est pas une faille en soi, puisque le code exécuté, même passé par la Minification, était déjà accessible, mais c'est une différence de confort réelle pour un lecteur curieux.
La règle pratique est simple : générez toujours les cartes, décidez ensuite de les servir ou de les envoyer uniquement à votre outil de suivi d'erreurs. Ce qu'il ne faut jamais faire, c'est ne pas les générer du tout : la première erreur de production sera alors impossible à situer.
Questions fréquentes
Les source maps ralentissent-elles le site ?
Non pour les visiteurs : le navigateur ne télécharge la carte que si les outils de développement sont ouverts. Le coût se situe au moment du build, qui devient plus long, et sur l'espace de stockage du serveur.
Pourquoi ma pile d'appels reste-t-elle illisible ?
Vérifiez d'abord que le fichier de carte est bien accessible à l'adresse annoncée par le commentaire final, une erreur 404 étant le cas le plus fréquent. Vérifiez ensuite que la carte correspond à la version déployée : un fichier régénéré après coup ne pointe plus les bonnes lignes.
Servent-elles aussi pour le CSS ?
Oui, et le principe est identique. Une feuille compilée depuis un préprocesseur ou générée par un outil renvoie vers le fichier d'origine dans l'inspecteur, ce qui évite de chercher à quel endroit une règle a bien pu être écrite.