ignoreList ソースマップ拡張機能

ソースマップ拡張機能「ignoreList」を使用すると、Chrome DevTools でのデバッグの利便性が向上します。

Jecelyn Yeen

Chrome DevTools では、ソースマップの ignoreList フィールドを解析し、デベロッパーのデバッグ操作の改善に役立てます。コンソールで、次のスタックトレースを確認します。DevTools では、すべてのサードパーティフレームが自動的に非表示になり、コードに関連するフレームのみが表示されます。

スタックトレースの結果の比較。 — この画像は、Chrome DevTools で `ignoreList` をサポートする前後のスタックトレースを示しています。後者では、無関係なサードパーティフレームを非表示にして、デバッグ中に問題をより迅速に特定できます。

`ignoreList` とは何ですか？

ソースマップ拡張機能は、ソースマップに関する補足情報を格納する追加のフィールドです。このようなフィールドには接頭辞 x_ が付きます。

Chrome DevTools では、ignoreList フィールド（指定されている場合）を使用して生成されたコードを除外し、ウェブデベロッパーが作成したコードだけに集中できるようにします。たとえば、次のソースマップを見てみましょう。

/* demo.js.map */

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

sources フィールドには、mappings エントリで使用されている元のソースのリストが表示されます。マッピングの仕組みについては、ソースマップとはをご覧ください。

node_modules/…/frameworks.js と node_modules/.../library.js の 2 つのファイルはサードパーティ製スクリプトであるため、ignoreList フィールドを指定して sources フィールド内の位置を指定できます。Chrome DevTools はこの情報を適用して、無視されたファイルでフレームを非表示にします。

閉じたスタックトレースと開いたスタックトレースの比較。 — この画像は、コンソールでスタックトレースを展開する前後のスタックトレースを示しています。無視されたフレームは、展開されるとグレー表示になります。

これは、ブレークポイントのデバッグ中の [Sources] パネルの [Call Stack] にも適用されます。

DevTools には、バックグラウンドで [既知のサードパーティスクリプトを自動的に無視リストに追加する] という追加設定がデフォルトで有効になっています。この設定は、DevTools > [設定] > [無視リスト] で確認できます。

ignoreList ソースマップフィールドを使用すると、[Sources] パネルで無視されるファイルを非表示にすることで、コードに集中できます。

無視リストに登録されているソースを非表示にする。

`ignoreList` の入力方法

幸いなことに、Angular や Nuxt などのフレームワークでは、ソースマップで ignoreList がすでに設定されています。最新バージョンにアップグレードすると、すぐに使用できます。スタックトレースを簡単に改善できます。

一方、Vite や Rollup などのビルドツールには、それを構成するための設定が用意されています。そのための webpack プラグインもあります。

フレームワークまたはライブラリの管理者の場合、これらの設定を実装してユーザーのデバッグエクスペリエンスを向上させる方法を理解しておくことが重要です。Angular と Nuxt がバックグラウンドでどのように機能したかについては、次のセクションをご覧ください。

お気に入りのフレームワークやビルドツールがまだサポートされていない場合はどうすればよいでしょうか。

Google は、こうした新しい設定を導入するためのフレームワークやツールの構築に積極的に取り組んでいます。また、この機能について管理者に通知することもできます。たとえば、リポジトリに問題を提出できます。

または、[DevTools] > [Sources] > [Page] ペインのファイルツリーから直接、無関係なスクリプトを [Ignore List] に手動で追加して、同様の結果を得ることもできます。

ケーススタディ: Nuxt と Angular の実装

次の 2 つのケーススタディをご覧ください。

Nuxt の `ignoreList`

Nuxt v3.3.1 以降、node_modules と Nuxt buildDir の内容は「デバッガで無視」としてマークされています。

これは、Vite と Rollup を使用して Nuxt のビルド構成を変更することで実現されました。

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

DevTools チームは、これを実現してくれた Vite チームと Nuxt チームに感謝の意を表します。この実装を成功に導くうえで、皆様のご協力とご協力に感謝いたします。Vite チームと Nuxt チームへのご協力に重ねてお礼申し上げます。

Angular の `ignoreList`

Angular v14.1.0 以降、node_modules フォルダと webpack フォルダの内容は「無視」とマークされています。

これは、webpack の Compiler モジュールにフックするプラグインを作成することで、angular-cli の変更により実現しました。

Google のエンジニアが作成した webpack プラグインは、PROCESS_ASSETS_STAGE_DEV_TOOLING ステージにフックして、ソースマップの ignoreList フィールドに Webpack が生成し、ブラウザが読み込む最終的なアセットを入力します。

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)));

DevTools での Angular デバッグのその他の改善点については、事例紹介: DevTools による Angular デバッグの改善をご覧ください。

Chrome DevTools チームは、この実装の成功に多大な貢献をしてくれた Angular チームに感謝の意を表します。皆さまのご協力とご協力が不可欠でした。ご協力に感謝いたします。これを実現してくれた Angular チームの皆さん、ありがとうございました。

ignoreList ソースマップ拡張機能

ignoreList とは何ですか？

ignoreList の入力方法