Source Map представляет собой связующий слой между скомпилированным кодом и исходными файлами проекта. В браузере он используется для восстановления оригинальной структуры JavaScript, TypeScript, CSS и других ресурсов при отладке. Корректность Source Map определяется тем, насколько точно DevTools способен сопоставить:
При корректной работе отображается исходный код, а не результат сборки (bundle), а ошибки указываются в оригинальных файлах проекта.
Первый этап валидации — убедиться, что Source Maps действительно генерируются Webpack.
Основные варианты конфигурации:
devtool: "source-map" — полный отдельный
.map файлdevtool: "eval-source-map" — встроенные карты для
dev-режимаdevtool: "hidden-source-map" — карты генерируются, но
не подключаются автоматическиSourceMapDevToolPlugin — ручная настройка
генерацииПроверка начинается с анализа итогового бандла:
sourceMappingURL.map файлов в output директорииПример признака корректной сборки:
//# sourceMappingURL=bundle.js.mapЕсли этой строки нет (при ожидаемой генерации), браузер не сможет загрузить карту.
Вкладка Network DevTools позволяет определить, был ли запрошен
.map файл.
Корректное поведение:
bundle.js.map200 OKТипичные проблемы:
404 Not Found — файл не попал в сборку или не
развернут403 Forbidden — ограничение доступа на сервереsourceMappingURLОсобое внимание требуется при использовании CDN: карты часто не деплоятся вместе с JS.
После загрузки карты необходимо проверить отображение структуры модулей:
src/index.ts)Если Source Map корректен, DevTools показывает дерево:
webpack://
└── project-name
└── src
└── index.jsНекорректные случаи:
Один из ключевых критериев корректности — отображение стека ошибок.
При корректной Source Map:
При проблемах:
bundle.jsОсобенно часто ошибки возникают при:
Минификация часто ломает соответствие, если карта построена неправильно.
Основные сценарии проверки:
Типичная ошибка:
console.log(user.name)a.a.bЕсли mapping корректный — DevTools показывает оригинальную строку.
При использовании TypeScript и Babel важно учитывать цепочку трансформаций:
TypeScript → Babel → Webpack → Terser
Каждый этап может нарушить mapping.
Критические проверки:
tsconfig.json содержит
"sourceMap": truesourceMaps: true)devtoolModuleFilenameTemplateТипичная проблема — двойная генерация Source Maps:
.map.map, не учитывая исходныйРезультат — смещение координат.
Source Maps применяются не только к JS, но и к CSS через loaders:
css-loadersass-loaderless-loaderВ DevTools проверяется:
.scss или .less файловТипичная ошибка:
styles.cssПричина часто в отключённом sourceMap: true в
loader’ах.
При использовании hidden-source-map карта генерируется,
но не подключается автоматически.
Проверка выполняется вручную:
.map файла на сервереsourceMappingURLЕсли карта существует, но не используется:
Webpack может искажать пути файлов при неправильной конфигурации:
src/src/index.js)webpack:// namespaceКлючевая настройка:
output: {
devtoolModuleFilenameTemplate: info =>
`webpack:///${info.resourcePath}`
}При неверной настройке Source Map становится формально валидным, но бесполезным.
Одна из частых ошибок — рассинхронизация файлов:
.map остался от старой сборкиПризнаки:
Методы проверки:
Корректность Source Maps проверяется через искусственно созданные ошибки:
throw new Error("test")Критерий:
Дополнительный уровень валидации — пошаговая отладка:
Если stepping ведёт в bundle — Source Map частично или полностью сломан.
Source Maps часто ломаются из-за кеша:
.map остаётся в cache storageПроверка:
В production окружении важно учитывать:
.mapКорректная диагностика:
application/json)