ignoreList 源映射扩展程序

使用 ignoreList 源代码映射扩展程序,提升 Chrome 开发者工具中的调试体验。

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

堆栈轨迹结果的比较。
此图片显示了 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.jsnode_modules/.../library.js 是第三方脚本,因此您可以指定 ignoreList 字段,以指明它们在 sources 字段中的位置。Chrome 开发者工具会应用这些信息来隐藏这些被忽略文件中的帧。

收起和展开后的堆栈轨迹的比较。
此图片显示了您在 Cloud 控制台中展开堆栈轨迹前后的堆栈轨迹。在展开时,忽略的帧会灰显。

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

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

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

隐藏已列入忽略列表的来源。

如何填充 ignoreList

值得高兴的是,AngularNuxt 等框架已经在其源代码映射中配置了 ignoreList。升级到最新版本即可立即使用。您可以轻松改进堆栈轨迹。

另一方面,ViteRollup 等构建工具提供了用于配置它的设置。此外,我们还有一个 webpack 插件

如果您是框架或库的维护者,则必须了解如何实现这些设置,以便改善用户的调试体验。请参阅以下部分,了解 Angular 和 Nuxt 是如何在后台完成这项操作的。

如果您喜欢的框架和构建工具还不支持它,该怎么办?

我们会积极使用框架和构建工具来实现这些新设置。您还可以通过告知维护者此功能来提供帮助。例如,您可以在其代码库中提交问题。

或者,您也可以直接从开发者工具 > Sources > Page 窗格上的文件树中手动向 Ignore List 添加不相关的脚本,以获得类似结果。

案例研究: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)
        },
      }
})

开发者工具团队衷心感谢 Vite 和 Nuxt 团队,使这一切成为可能。非常感谢您的努力与合作,这对此次实施的成功至关重要。再次感谢 Vite 和 Nuxt 团队做出的贡献!

Angular 中的 ignoreList

Angular v14.1.0 开始,node_moduleswebpack 文件夹中的内容已被标记为“要忽略”

这是通过创建可与 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 团队,谢谢你们让这一切成为可能!