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] パネルに表示されるコールスタックにも当てはまります。

DevTools では、舞台裏で、[既知の第三者のスクリプトを無視リストに自動追加] という追加の設定がデフォルトで有効になっています。この設定は、DevTools > [設定] > [無視リスト] で確認できます。

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

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 の変更によって実現されました。

Google のエンジニアが作成した 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 チームに感謝します。