Карта исходного кода

Код, который отдаётся браузеру, часто мало похож на написанный: TypeScript и современный JavaScript прогоняют через транспилятор, десятки модулей склеивают в один файл, имена переменных сокращают до одной буквы, SCSS превращают в CSS. Ошибка в такой сборке указывает на «строку 1, столбец 48213», и это ничего не говорит. Карта исходного кода (source map) решает задачу: инструменты разработчика читают её, показывают исходный файл и строку и позволяют ставить точки останова прямо в нём.

Как устроен файл

Это JSON, обычно с расширением .map, рядом с собранным файлом:

{
  "version": 3,
  "file": "app.min.js",
  "sources": ["src/cart.ts", "src/api.ts"],
  "names": ["addToCart", "request"],
  "mappings": "AAAA,SAASA,UAAU..."
}

Поле mappings хранит закодированные в Base64 VLQ соответствия позиций, sources — список исходников, а необязательное sourcesContent может содержать их текст целиком. Браузер находит карту по комментарию в конце собранного файла — //# sourceMappingURL=app.min.js.map, в CSS — /*# sourceMappingURL=… */ — или по HTTP-заголовку SourceMap. Загружается она, только когда открыты инструменты разработчика.

Включение в сборке

Карты создаёт сборщик или компилятор: в Vite — параметр build.sourcemap, в webpack — devtool, у esbuild — флаг --sourcemap, в TypeScript — опция sourceMap в tsconfig.json. Dart Sass при компиляции в файл создаёт карты по умолчанию. Как пользоваться ими при пошаговой отладке — в статье про отладчик.

Выкладывать ли на рабочий сайт

Публичная карта с sourcesContent отдаёт любому желающему исходники проекта: структуру, комментарии, а иногда и забытые адреса внутренних сервисов. Поэтому на рабочем сервере карты либо не публикуют, либо создают «скрытыми» — без ссылки в собранном файле — и загружают только в систему отслеживания ошибок, чтобы та показывала понятные трассировки. Если карта всё же лежит рядом с файлом, стоит хотя бы закрыть доступ к *.map в настройках веб-сервера.