ignoreList 源映射扩展程序

使用 ignoreList 源映射扩展程序改善 Chrome 开发者工具中的调试体验。

Jecelyn Yeen

Chrome 开发者工具会解析源代码映射中的 ignoreList 字段，以帮助改善开发者调试体验。在控制台中查看以下堆栈轨迹。开发者工具会自动隐藏所有第三方框架，仅显示与您的代码相关的框架。

堆栈轨迹结果对比。 — 此图片显示了 Chrome 开发者工具支持 `ignoreList` 前后的堆栈轨迹。后者会隐藏不相关的第三方帧，帮助您在调试期间更快地查明问题。

什么是 `ignoreList`？

源映射扩展是附加字段，用于存储源映射的补充信息。此类字段的前缀为 x_。

Chrome 开发者工具会使用 ignoreList 字段（如有提供）来滤除生成的代码，让 Web 开发者只专注于自己编写的代码。例如，请查看以下源代码映射。

/* 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 两个文件是第三方脚本，您可以指定 ignoreList 字段以指示它们在 sources 字段中的位置。Chrome 开发者工具将应用这些信息，以隐藏这些被忽略的文件中的帧。

收起和展开的堆栈轨迹的对比。 — 此图片显示了在控制台中展开堆栈轨迹前后的堆栈轨迹。忽略的帧在展开时呈灰显状态。

在断点调试期间，这也适用于 Sources 面板中的 Call Stack。

在后台，开发者工具会默认启用一项额外设置：自动将已知的第三方脚本添加到忽略列表。您可以在开发者工具 > Settings > Ignore List 中找到它。

使用 ignoreList 源代码映射字段，您可以在 Sources 面板中隐藏忽略的文件，以专注于您的代码。

隐藏已列入忽略名单的来源。

如何填充`ignoreList`

好消息是，Angular 和 Nuxt 等框架在其源代码映射中已经配置了 ignoreList。升级到最新版本，无需额外设置即可使用。您可以轻松实现堆栈轨迹方面的改进。

另一方面，Vite 和 Rollup 等构建工具提供用于进行配置的设置。您也可以通过Webpack 插件完成此操作。

如果您是框架或库维护人员，请务必了解如何实现这些设置，以便提升用户的调试体验。请参阅以下部分，了解 Angular 和 Nuxt 如何在后台完成这项工作。

如果您喜欢的框架和构建工具尚不支持它，该怎么办？

我们会积极使用框架和构建工具，以采用这些新设置。您也可以将此功能告知维护人员。例如，您可以在客户的代码库中提交问题。

或者，您也可以直接从开发者工具 > Sources > Page 窗格的文件树中手动将不相关的脚本添加到忽略列表，以获得类似结果。

案例研究：Nuxt 和 Angular 实现

请参阅以下两个案例研究。

Nuxt 中的 `ignoreList`

从 Nuxt v3.3.1 开始，node_modules 和 Nuxt buildDir 的内容已标记为“可由调试程序忽略”。

这是通过使用 Vite 和 Rollup 对 Nuxt 的 build 配置进行更改来实现的：

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

如需详细了解开发者工具中的其他 Angular 调试改进，请参阅案例研究：使用开发者工具更好地进行 Angular 调试。

Chrome 开发者工具团队在此衷心感谢 Angular 团队对此次实现成功做出的宝贵贡献。您的努力和协作至关重要，感谢您的努力。感谢 Angular 团队让这一切成为可能！

ignoreList 源映射扩展程序

什么是 ignoreList？

如何填充ignoreList