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 エントリで使用された元のソースのリストが表示されます。マッピングの仕組みについては、ソースマップとはをご覧ください。

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

折りたたまれたスタックトレース（左）と展開されたスタックトレース（右）。 — この画像は、Console でスタックトレースを展開する前後のスタックトレースを示しています。展開すると、無視したフレームがグレー表示されます。

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

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

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

無視リストに含まれるソースを非表示にします。

`ignoreList` にデータを入力する方法

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

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

フレームワークやライブラリのメンテナンス担当者は、ユーザーのデバッグエクスペリエンスを改善するために、これらの設定を実装する方法を理解することが重要です。Angular と Nuxt がバックグラウンドで行った処理については、次のセクションをご覧ください。

使用しているフレームワークやビルドツールがまだサポートしていない場合はどうすればよいですか？

Google は、これらの新しい設定を導入するために、フレームワークとビルドツールを積極的に活用しています。メンテナンス担当者にこの機能について通知することもできます。たとえば、リポジトリに問題を報告できます。

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

事例紹介: 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 を変更することで実現されました。

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

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 にデータを入力する方法