Расширение ignoreList для карты исходного кода

Улучшите отладку в инструментах разработчика Chrome с помощью расширения ignoreList.

Jecelyn Yeen

Инструменты разработчика Chrome анализируют поле ignoreList в файлах source map, чтобы упростить отладку. Посмотрите на следующую трассировку стека в Консоли. Инструменты разработчика автоматически скрывают все сторонние фреймы и показывают только те, которые относятся к вашему коду.

На изображении показаны трассировки стека до и после того, как инструменты разработчика Chrome стали поддерживать ignoreList. Второй вариант скрывает нерелевантные сторонние фреймы, чтобы вы могли быстрее выявлять проблемы во время отладки.

Что такое ignoreList?

Расширения файлов source map – это дополнительные поля, в которых хранится дополнительная информация о файле source map. Названия таких полей начинаются с x_.

Инструменты разработчика Chrome используют поле 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 являются сторонними скриптами, вы можете указать поле ignoreList, чтобы обозначить их позиции в поле sources. Инструменты разработчика Chrome будут использовать эту информацию, чтобы скрывать фреймы из игнорируемых файлов.

На изображении показаны трассировки стека до и после развертывания трассировки стека в консоли. Игнорируемые фреймы выделены серым цветом.

Это также относится к стеку вызовов на панели Источники во время отладки точек останова.

В инструментах разработчика по умолчанию включен параметр Автоматически добавлять известные сторонние скрипты в список игнорирования. Чтобы найти его, откройте Инструменты разработчика и выберите Настройки > Список игнорирования.

Поле ignoreList карты исходного кода позволяет скрыть игнорируемые файлы на панели Источники, чтобы сосредоточиться на своем коде.

Как заполнить ignoreList

Хорошая новость заключается в том, что такие фреймворки, как Angular и Nuxt, уже настраивают ignoreList в своих файлах source map. Обновите его до последней версии, и все заработает. Вы получаете улучшенные трассировки стека без лишних усилий.

С другой стороны, инструменты сборки, такие как Vite и Rollup, предоставляют настройки для его настройки. Для этого также есть плагин webpack.

Если вы поддерживаете фреймворк или библиотеку, вам необходимо знать, как реализовать эти настройки, чтобы улучшить процесс отладки для пользователей. В следующем разделе показано, как это реализовано в Angular и Nuxt.

Что делать, если ваш любимый фреймворк и инструмент сборки пока не поддерживают его?

Мы активно работаем с фреймворками и инструментами сборки, чтобы внедрить эти новые настройки. Вы также можете сообщить об этой функции администраторам. Например, вы можете сообщить о проблеме в хранилище.

Вы также можете вручную добавить ненужные скрипты в список игнорирования прямо из дерева файлов на панели "Инструменты разработчика > Источники > Страница".

Примеры использования: реализация Nuxt и Angular

Рассмотрим два примера.

ignoreList в Nuxt

Начиная с Nuxt версии 3.3.1, содержимое node_modules и Nuxt buildDir помечается как игнорируемое отладчиками.

Это было достигнуто за счет изменения конфигурации сборки Nuxt с использованием Vite и Rollup:

/* 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 за вклад в развитие экосистемы.

ignoreList в Angular

Начиная с Angular версии 14.1.0, содержимое папок node_modules и webpack помечается как игнорируемое.

Это было достигнуто за счет изменения в angular-cli путем создания плагина, который подключается к модулю Compiler webpack.

Плагин webpack, созданный нашими инженерами, подключается к этапу PROCESS_ASSETS_STAGE_DEV_TOOLING и заполняет поле ignoreList в файлах sourcemap конечными объектами, которые генерирует 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)));

Чтобы узнать больше об улучшениях отладки Angular в инструментах разработчика, прочитайте статью Case Study: Better Angular Debugging with DevTools (на английском языке).

Команда инструментов разработчика Chrome выражает благодарность команде Angular за неоценимый вклад в успешную реализацию этой функции. Мы ценим ваши усилия и сотрудничество. Спасибо команде Angular за то, что это стало возможным!