6.3. Исходные карты

Что такое source map

Source map — это исходный код (текст) приложения. Это понятие уже не ново, но вместе с тем большинство начинающих разработчиков не знают о его существовании.

Для любого фронтендера DevTools является неотъемлемой частью работы, а source map — вспомогательный инструмент, упрощающий ведение отладки (дебага).

Что нужно для работы source map:

  • непосредственно сам JS-код;
  • набор файлов с исходным кодом — те самые карты.

Откуда всё это брать?

Сначала нужно проверить, включена ли у вас поддержка исходных карт в самом браузере. По умолчанию они всегда включены, но проверить всё же стоит.

Делается это так:

  • открываете DevTools;
  • находите settings (троеточие);
  • в настройках в разделе advanced нажимаете чекбокс source map или «Исходные карты», если ваш браузер на русском.
Включение исходных карт на примере браузера Firefox

После включаем создание исходных карт в конфиге webpack.

В файле webpack.prod.js:

module.exports = {
  mode: 'production',
  devtools: 'source-map'
  /* Здесь остальной код конфига...*/
}

В файле webpack.dev.js:

 module.exports = {
  mode: 'development',
  devtool: 'inline-source-map',
  /* Здесь остальной код конфига...*/
}

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

Файл карты
Файл исходной карты после сборки
Директория с файлами
Директория с файлами, появившимися в результате включения исходных карт (видна только в браузере)

Структура самих исходных карт:

{
  "version": 3,
  "file": "out.js",
  "sourceRoot": "",
  "sources": [
    "foo.js",
    "bar.js"
  ],
  "sourcesContent": [
    null,
    null
  ],
  "names": [
    "src",
    "maps",
    "are",
    "fun"
  ],
  "mappings": "A,AAAB;;ABCDE;"
}

Пример взят из официальной документации

Давайте разберём основные поля этого файла.

version — версия исходных карт.

file — имя получившегося файла, к которому относится текущий map-файл (index.js и его исходная карта index.map.js). Необязательное поле.

sourceRoot — префикс для путей к исходникам. Необязательное поле.

sources — список путей к исходникам с указанием директорий, например src.

sourcesContent — список строк, каждая из которых содержит исходный текст файла. Необязательное поле.

names — список имён в формате массива, где лежат имена переменных и функций, которые подверглись изменению в сгенерированном файле.

mappings — координаты переменных и функций исходных файлов на сгенерированный файл в формате Base64 VLQ.

То, что будет написано в созданном файле, также невозможно прочитать. Однако теперь при запуске проекта локально мы можем с помощью DevTools видеть исходники проекта в не минимизированном виде и отлавливать баги.

Не рекомендуется оставлять данный параметр включённым, при деплое финальной версии проекта — это может привести к утечке данных.

Подытожим порядок действий для работы с исходными файлами проекта.

  1. Проверяем в настройках браузера, что поддержка исходных карт включена.
  2. Далее в зависимости от режима разработки в поле devtools мы включаем исходники: source-map — если production-режим, иначе — inline-source-map.
  3. В режиме разработки включённые исходники позволяют выделить именно ту часть кода, где возникла ошибка — без преобразований. И видно это будет в открытом окне браузера без дополнительных манипуляций.
  4. Перед деплоем для дополнительного дебага собираем проект в production-режиме и при помощи встроенных в редактор кода плагинов (LiveServer) проверяем index.html. Открываем последний в новом окне браузера и во вкладке с файлами DevTools видим несколько директорий:
  • текущую;
  • webpack (как на скриншоте выше), где размещены все исходные файлы без преобразований.
  1. После дебага убираем включённые исходники из конфига, иначе при деплое они будут видны всем пользователям, которые знают, где и как их смотреть.