Que sont les cartes sources ?

Jecelyn Yeen

Les cartes sources sont un outil essentiel du développement Web moderne, beaucoup plus facilement. Cette page décrit les bases des cartes sources, leur utilisation générées et comment elles améliorent l'expérience de débogage.

Le besoin de mappages sources

Les premières applications Web ont été conçues avec une faible complexité. Les développeurs ont déployé du code HTML, CSS et JavaScript directement sur le Web.

Les applications Web plus modernes et complexes peuvent avoir besoin de divers outils pour le workflow de développement d'applications. Exemple :

<ph type="x-smartling-placeholder">
</ph> Brève présentation des différents outils.
Quelques outils de développement d'applications Web courants.

Ces outils nécessitent un processus de compilation pour convertir votre code en code HTML standard, JavaScript et CSS compréhensibles par les navigateurs. Il est également courant de d'optimiser les performances en réduisant et en combinant la taille de ces fichiers, à l'aide d'un outil comme Terser :

Par exemple, à l'aide d'outils de compilation, nous pouvons transpiler et compresser TypeScript en une seule ligne de code JavaScript. Vous pouvez l’essayer par vous-même dans cette démonstration sur GitHub.

/* A TypeScript demo: example.ts */

document.querySelector('button')?.addEventListener('click', () => {
  const num: number = Math.floor(Math.random() * 101);
  const greet: string = 'Hello';
  (document.querySelector('p') as HTMLParagraphElement).innerText = `${greet}, you are no. ${num}!`;
  console.log(num);
});

Une version compressée serait la suivante:

/* A compressed JavaScript version of the TypeScript demo: example.min.js  */

document.querySelector("button")?.addEventListener("click",(()=>{const e=Math.floor(101*Math.random());document.querySelector("p").innerText=`Hello, you are no. ${e}!`,console.log(e)}));

Toutefois, la compression de votre code peut rendre le débogage plus difficile. Cartes sources vous pouvez résoudre ce problème: en mappant votre code compilé sur le code d'origine, ils peuvent vous aider à trouver rapidement la source d'une erreur.

Générer des mappages sources

Les cartes sources sont des fichiers dont le nom se termine par .map (par exemple, example.min.js.map et styles.css.map). Ils peuvent être générés par la plupart des tels que Vite, webpack, Regroupement, Parcel et esbuild.

Certains outils incluent des mappages sources par défaut. D'autres pourraient avoir besoin pour les générer:

/* Example configuration: vite.config.js */
/* https://vitejs.dev/config/ */

export default defineConfig({
  build: {
    sourcemap: true, // enable production source maps
  },
  css: {
    devSourcemap: true // enable CSS source maps during development
  }
})

Comprendre la carte source

Pour faciliter le débogage, ces fichiers de carte source contiennent des informations essentielles sur la façon dont le code compilé est mappé au code d’origine. Voici un exemple carte source:

{
  "mappings": "AAAAA,SAASC,cAAc,WAAWC, ...",
  "sources": ["src/script.ts"],
  "sourcesContent": ["document.querySelector('button')..."],
  "names": ["document","querySelector", ...],
  "version": 3,
  "file": "example.min.js.map"
}

Pour comprendre chacun de ces champs, vous pouvez consulter les spécifications de la carte source ou Anatomie d'une carte source :

La partie la plus importante d'une carte source est le champ mappings. Elle utilise un Chaîne encodée au format VLQ en base64 pour faire correspondre les lignes et les emplacements du fichier compilé à l'original correspondant . Vous pouvez visualiser ce mappage à l'aide d'un visualiseur de carte source tel que source-map-visualization ou Source Map Visualization :

<ph type="x-smartling-placeholder">
</ph> Une visualisation de la carte source. <ph type="x-smartling-placeholder">
</ph> Représentation visuelle de l'exemple de code précédent, générée par un visualiseur.

La colonne generated (générée) à gauche affiche le contenu compressé et le La colonne original affiche la source d'origine.

Le visualiseur attribue un code couleur à chaque ligne de la colonne d'origine avec ses le code correspondant dans la colonne generated.

La section mappings affiche les mappages décodés du code. Par exemple, l'entrée 65 -> 2:2 signifie:

  • Code généré: le mot const commence à la position 65 dans le contenu compressé.
  • Code d'origine: le mot const commence à la ligne 2 et à la colonne 2 dans le contenu d'origine.
<ph type="x-smartling-placeholder">
</ph> Entrée de mappage.
La visualisation de la cartographie, axée sur l'entrée 65 -> 2:2.

Cela permet aux développeurs d'identifier rapidement la relation entre le code réduit et le code d'origine, ce qui rend le débogage plus fluide.

Les outils pour les développeurs du navigateur appliquent ces cartes sources pour vous aider à identifier à déboguer rapidement les problèmes dans le navigateur.

<ph type="x-smartling-placeholder">
</ph> Outils pour les développeurs appliquant une carte source
Exemple d'application des outils pour les développeurs de navigateurs sources et afficher les mappages entre les fichiers.

Extensions de carte source

Les mappages sources acceptent les champs d'extension personnalisés qui commencent par le préfixe x_. Un exemple est le champ d'extension x_google_ignoreList proposé par Chrome DevTools. Voir x_google_ignoreList pour découvrir comment ces extensions vous aident à vous concentrer sur votre code.

Inconvénients de la carte source

Malheureusement, les mappages de sources ne sont pas toujours aussi complets que vous le souhaitez. Dans notre premier exemple, la variable greet a été optimisée lors de la compilation même si sa valeur est directement intégrée à la sortie finale de la chaîne.

<ph type="x-smartling-placeholder">
</ph> Le message d&#39;accueil variable n&#39;est pas mappé.
La variable greet dans l'original code manquant dans le mappage.

Dans ce cas, lorsque vous déboguez le code, il est possible que les outils pour les développeurs ne puissent pas déduire et afficher la valeur réelle. Ce type d'erreur peut rendre votre code la surveillance et l'analyse.

<ph type="x-smartling-placeholder">
</ph> Le message d&#39;accueil variable n&#39;est pas défini.
L'outil pour les développeurs ne trouve aucune valeur pour greet.

Il s'agit d'un problème qui doit être résolu dans la conception des cartes sources. Un La solution potentielle consiste à inclure les informations de portée dans les cartes sources dans de la même manière que les autres langages de programmation avec leurs informations de débogage.

Cependant, tout l'écosystème doit collaborer pour améliorer les spécifications et la mise en œuvre de la carte source. Pour suivre l'activité en cours sur améliorer le débogage avec les cartes sources, reportez-vous à la proposition de Source Maps v4 sur GitHub.