Quellzuordnungserweiterung „ignoreList“

Mit der Source Map-Erweiterung ignoreList können Sie das Debugging in den Chrome-Entwicklertools verbessern.

Jecelyn Yeen

Die Chrome-Entwicklertools parsen das Feld ignoreList in Quellzuordnungen, um das Debugging für Entwickler zu verbessern. Sehen Sie sich den folgenden Stacktrace in der Console an. In den Entwicklertools werden alle Drittanbieter-Frames automatisch ausgeblendet und nur die Frames angezeigt, die für Ihren Code relevant sind.

Das Bild zeigt die Stack-Traces vor und nach der Unterstützung von ignoreList durch die Chrome-Entwicklertools. Letzteres blendet irrelevante Frames von Drittanbietern aus, damit Sie Probleme beim Debugging schneller finden können.

Was ist ignoreList?

Quellzuordnungserweiterungen sind zusätzliche Felder, in denen ergänzende Informationen zur Quellzuordnung gespeichert werden. Solche Felder haben das Präfix x_.

Die Chrome-Entwicklertools verwenden das Feld ignoreList (falls vorhanden), um generierten Code herauszufiltern, damit sich Webentwickler nur auf den von ihnen erstellten Code konzentrieren können. Sehen Sie sich beispielsweise die folgende Quellzuordnung an.

/* demo.js.map */

{
  "version": 3,
  "mappings": "AAAAA, ..."
  "sources": [
    "app.js",
    "components/Button.ts",
    "node_modules/.../framework.js",
    "node_modules/.../library.js",
    ...
  ],
  "ignoreList": [2, 3],
  ...
}

Im Feld sources wird eine Liste der ursprünglichen Quellen angezeigt, die vom Eintrag mappings verwendet werden. Im Video What are source maps? (Was sind Quellzuordnungen?) erfahren Sie, wie die Zuordnungen funktionieren.

Da die beiden Dateien node_modules/…/frameworks.js und node_modules/.../library.js Drittanbieterskripts sind, können Sie das Feld ignoreList angeben, um ihre Positionen im Feld sources anzugeben. Die Chrome-Entwicklertools verwenden diese Informationen, um Frames aus diesen ignorierten Dateien auszublenden.

Das Bild zeigt die Stacktraces vor und nach dem Maximieren des Stacktraces in der Console. Die ignorierten Frames werden ausgegraut, wenn sie maximiert werden.

Das gilt auch für den Aufrufstapel im Bereich Quellen während des Debuggings von Haltepunkten.

Hinter den Kulissen ist in den Entwicklertools standardmäßig eine zusätzliche Einstellung aktiviert: Bekannte Drittanbieterskripts automatisch der Ignorieren-Liste hinzufügen. Sie finden sie in den DevTools unter Einstellungen > Ignorierliste.

Mit dem Quellzuordnungsfeld ignoreList können Sie die ignorierten Dateien im Bereich Quellen ausblenden, um sich auf Ihren Code zu konzentrieren.

ignoreList füllen

Die gute Nachricht ist, dass Frameworks wie Angular und Nuxt ignoreList bereits in ihren Quellzuordnungen konfigurieren. Führen Sie ein Upgrade auf die aktuelle Version durch, damit die Funktion sofort einsatzbereit ist. Sie erhalten Stacktrace-Verbesserungen ohne Aufwand.

Build-Tools wie Vite und Rollup bieten dagegen Einstellungen, um es zu konfigurieren. Dafür gibt es auch ein webpack-Plug-in.

Wenn Sie ein Framework oder eine Bibliothek verwalten, ist es wichtig zu wissen, wie Sie diese Einstellungen implementieren, um die Fehlerbehebung für Ihre Nutzer zu verbessern. Im folgenden Abschnitt erfahren Sie, wie Angular und Nuxt das im Hintergrund umgesetzt haben.

Was ist, wenn Ihr bevorzugtes Framework und Build-Tool es noch nicht unterstützt?

Wir arbeiten aktiv mit Frameworks und Build-Tools zusammen, um diese neuen Einstellungen zu implementieren. Sie können auch helfen, indem Sie die Maintainer über diese Funktion informieren. Sie können beispielsweise ein Problem in ihrem Repository melden.

Alternativ können Sie irrelevante Skripts manuell zur Ignorierliste hinzufügen, und zwar direkt über die Dateistruktur im Bereich „DevTools“ > Quellen > Seite, um ein ähnliches Ergebnis zu erzielen.

Fallstudien: Nuxt- und Angular-Implementierung

Sehen Sie sich die folgenden beiden Fallstudien an.

ignoreList in Nuxt

Ab Nuxt v3.3.1 werden die Inhalte von node_modules und Nuxt buildDir als von Debuggern zu ignorieren markiert.

Dies wurde durch eine Änderung der Build-Konfiguration von Nuxt mit Vite und Rollup erreicht:

/* vite.config.ts */

const ctx: ViteBuildContext = {
  config: vite.mergeConfig(
  build: {
    rollupOptions: {
      output: {
        sourcemapIgnoreList: (relativeSourcePath) => {
          return relativeSourcePath.includes('/node_modules/') || relativeSourcePath.includes(ctx.nuxt.options.buildDir)
        },
      }
})

Das DevTools-Team möchte sich bei den Vite- und Nuxt-Teams dafür bedanken, dass sie dies möglich gemacht haben. Wir wissen Ihre Bemühungen und Ihre Zusammenarbeit zu schätzen, die für den Erfolg dieser Implementierung entscheidend waren. Vielen Dank an die Vite- und Nuxt-Teams für ihre Beiträge.

ignoreList in Angular

Ab Angular v14.1.0 werden die Inhalte der Ordner node_modules und webpack als „zu ignorieren“ markiert.

Dies wurde durch eine Änderung in angular-cli erreicht, indem ein Plug-in erstellt wurde, das sich in das Compiler-Modul von webpack einbindet.

Das von unseren Entwicklern erstellte webpack-Plug-in greift in die PROCESS_ASSETS_STAGE_DEV_TOOLING-Phase ein und füllt das Feld ignoreList in den Quellzuordnungen mit den endgültigen Assets, die von webpack generiert und vom Browser geladen werden.

const map = JSON.parse(mapContent) as SourceMap;
const ignoreList = [];

for (const [index, path] of map.sources.entries()) {
  if (path.includes('/node_modules/') || path.startsWith('webpack/')) {
    ignoreList.push(index);
  }
}

map[`ignoreList`] = ignoreList;
compilation.updateAsset(name, new RawSource(JSON.stringify(map)));

Weitere Informationen zu anderen Verbesserungen beim Debugging von Angular in den Entwicklertools finden Sie in der Fallstudie: Besseres Debugging von Angular mit den Entwicklertools.

Das Chrome-Entwicklertools-Team möchte dem Angular-Team für seinen unschätzbaren Beitrag zum Erfolg dieser Implementierung danken. Ihre Bemühungen und Ihre Zusammenarbeit waren entscheidend und wir wissen Ihre harte Arbeit zu schätzen. Vielen Dank an das Angular-Team, das dies möglich gemacht hat!