Опция sourcemap в esbuild управляет тем, как формируются
source map-файлы, связывающие итоговый JavaScript-код с исходными
файлами. Это критически важно для отладки, поскольку позволяет дебаггеру
показывать оригинальный TypeScript или современный JavaScript вместо
минифицированного или транспилированного результата.
В esbuild поведение sourcemap задаётся строковым режимом
и влияет на структуру выходных артефактов, способ подключения карт и
способ их хранения.
Source map — это JSON-структура, которая содержит соответствия между:
Минимальный результат работы source map — файл .map,
который может быть подключён к итоговому JavaScript через директиву:
//# sourceMappingURL=bundle.js.mapили встроен непосредственно в файл.
Режим inline помещает source map непосредственно внутрь
итогового JavaScript-файла.
.map файл не создаётсяimport * as esbuild from 'esbuild';
esbuild.build({
entryPoints: ['src/index.js'],
bundle: true,
outfile: 'dist/bundle.js',
sourcemap: 'inline'
});В конце bundle.js появляется:
//# sourceMappingURL=dat a:application/json;base64,eyJ2ZXJzaW9uIjo...Режим external создаёт отдельный .map файл
и подключает его через ссылку в конце JavaScript-файла.
bundle.js.mapesbuild.build({
entryPoints: ['src/index.js'],
bundle: true,
outfile: 'dist/bundle.js',
sourcemap: 'external'
});Структура выходной директории:
dist/
├── bundle.js
└── bundle.js.mapВ bundle.js:
//# sourceMappingURL=bundle.js.map.js и .map
отдельноРежим linked в esbuild по поведению близок к
external, но делает акцент на явной связке source map с
выходным файлом через стандартный механизм ссылок.
.map файлsourceMappingURLesbuild.build({
entryPoints: ['src/index.js'],
bundle: true,
outfile: 'dist/app.js',
sourcemap: 'linked'
});dist/
├── app.js
└── app.js.mapВ конце app.js:
//# sourceMappingURL=app.js.mapФормально linked и external в esbuild
пересекаются по поведению, но концептуально:
linked подчёркивает связь через URL-указательexternal описывает сам факт вынесения map наружуВ реальных сборках esbuild эти режимы часто ведут к одинаковому результату, но различие важно при работе через разные интеграции или инструменты, которые могут интерпретировать режимы по-разному.
Режим both включает сразу два способа представления
source map:
.map файлesbuild.build({
entryPoints: ['src/index.js'],
bundle: true,
outfile: 'dist/bundle.js',
sourcemap: 'both'
});Создаются два механизма отображения:
bundle.js присутствует inline base64 source
mapbundle.js.map.mapГенерация source map в esbuild добавляет этап постобработки:
Режим inline обычно быстрее на этапе загрузки (меньше
файлов), но тяжелее по размеру итогового бандла. Режимы
external, linked и both
увеличивают количество файлов, но облегчают сетевую доставку JS.
При включённом minify source map сохраняет связь
между:
В режимах external, linked,
both это особенно важно, поскольку позволяет инструментам
восстановления стека точно сопоставлять ошибки с исходниками.
В режиме watch: true esbuild обновляет source map при
каждом изменении исходных файлов.
inline — пересборка одного файлаexternal/linked — пересборка JS и mapboth — полная пересборка двух представлений.mapSource map, сгенерированные esbuild, совместимы с: