Was sind Quellzuordnungen?

Jecelyn Yeen

Quellkarten sind ein wichtiges Tool bei der modernen Webentwicklung, das das Debuggen erheblich erleichtert. Auf dieser Seite erfahren Sie die Grundlagen von Quellkarten, wie sie generiert werden und wie sie das Debuggen verbessern.

Die Notwendigkeit von Quellkarten

Frühe Web-Apps waren relativ einfach. Entwickler haben HTML-, CSS- und JavaScript-Dateien direkt im Web bereitgestellt.

Moderne und komplexe Webanwendungen erfordern unter Umständen eine Vielzahl von Tools im Entwicklungsworkflow. Beispiel:

• Vorlagensprachen und HTML-Preprocessor: Pug, Nunjucks, Markdown.
• CSS-Präprozessoren: SCSS, LESS, PostCSS.
• JavaScript-Frameworks: Angular, React, Vue, Svelte.
• JavaScript-Meta-Frameworks: Next.js, Nuxt, Astro
• Hochsprachen: TypeScript, Dart, CoffeeScript

Für diese Tools ist ein Build-Prozess erforderlich, um Ihren Code in standardmäßiges HTML, JavaScript und CSS zu transpilieren, das von Browsern verstanden werden kann. Es ist auch üblich, die Leistung durch Minimieren und Kombinieren dieser Dateien mit einem Tool wie Terser zu optimieren.

Mit Build-Tools können wir beispielsweise die folgende TypeScript-Datei in eine einzelne Zeile JavaScript transpilieren und komprimieren. In dieser Demo auf GitHub können Sie es selbst ausprobieren.

/* 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);
});

Eine komprimierte Version würde so aussehen:

/* 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)}));

Das Komprimieren Ihres Codes kann jedoch das Debugging erschweren. Mit Quellzuordnungen lässt sich dieses Problem beheben: Indem Sie den kompilierten Code wieder dem ursprünglichen Code zuordnen, können Sie die Ursache eines Fehlers schneller finden.

Quellkarten generieren

Quellzuordnungen sind Dateien, deren Namen auf .map enden, z. B. example.min.js.map und styles.css.map. Sie können von den meisten Build-Tools generiert werden, einschließlich Vite, Webpack, Rollup, Parcel und esbuild.

Einige Tools enthalten standardmäßig Quellkarten. Andere benötigen möglicherweise eine zusätzliche Konfiguration, um sie zu erstellen:

/* 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
  }
})

Quellzuordnung

Diese Source Map-Dateien enthalten wichtige Informationen darüber, wie der kompilierte Code dem ursprünglichen Code zugeordnet ist, um die Fehlerbehebung zu erleichtern. Hier ein Beispiel für eine Quellkarte:

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

Weitere Informationen zu diesen Feldern finden Sie in der Spezifikation für Quellkarten oder im Artikel Die Anatomie einer Quellkarte.

Der wichtigste Teil einer Quellkarte ist das Feld mappings. Dabei wird ein VLQ Base64-codierter String verwendet, um Zeilen und Speicherorte in der kompilierten Datei der entsprechenden Originaldatei zuzuordnen. Sie können sich diese Zuordnung mit einem Source Map-Visualizer wie source-map-visualization oder Source Map-Visualisierung ansehen.

In der Spalte generiert auf der linken Seite sind die komprimierten Inhalte zu sehen. In der Spalte Original ist die Originalquelle zu sehen.

Im Visualisierungstool wird jede Zeile in der Spalte original mit dem entsprechenden Code in der Spalte generiert codiert.

Im Abschnitt Zuordnungen werden decodierte Zuordnungen des Codes angezeigt. Beispiel: Der Eintrag 65 -> 2:2 bedeutet:

• Generierter Code: Das Wort const beginnt in den komprimierten Inhalten an Position 65.
• Original-Code: Das Wort const beginnt in Zeile 2 und Spalte 2 im Originalinhalt.

So können Entwickler schnell die Beziehung zwischen dem minimierten Code und dem ursprünglichen Code ermitteln, was die Fehlerbehebung erleichtert.

Mithilfe dieser Quellkarten können Sie mit Browser-Entwicklertools Probleme beim Debuggen im Browser schnell ermitteln.

Quellzuordnungserweiterungen

Quellzuordnungen unterstützen benutzerdefinierte Erweiterungsfelder, die mit dem Präfix x_ beginnen. Ein Beispiel ist das von den Chrome DevTools vorgeschlagene Erweiterungsfeld x_google_ignoreList. Unter x_google_ignoreList erfahren Sie, wie Sie sich mithilfe dieser Erweiterungen auf Ihren Code konzentrieren können.

Nachteile von Quellzuordnungen

Leider sind Quellzuordnungen nicht immer so vollständig, wie sie sein müssen. In unserem ersten Beispiel wurde die Variable greet während des Build-Prozesses entfernt, obwohl ihr Wert direkt in die endgültige Stringausgabe eingebettet ist.

In diesem Fall können Entwicklertools beim Entfernen von Fehlern möglicherweise nicht den tatsächlichen Wert ableiten und anzeigen. Diese Art von Fehler kann das Monitoring und die Analyse von Code erschweren.

Dieses Problem muss beim Entwerfen von Quellkarten gelöst werden. Eine mögliche Lösung besteht darin, in den Quellkarten Informationen zum Geltungsbereich anzugeben, ähnlich wie es in anderen Programmiersprachen mit ihren Debug-Informationen der Fall ist.

Dazu muss jedoch das gesamte System zusammenarbeiten, um die Spezifikation und Implementierung der Quellkarte zu verbessern. Aktuelle Informationen zur Verbesserung der Fehlerbehebung mit Quellkarten finden Sie im Vorschlag für Source Maps v4 auf GitHub.