Работа source maps при минификации

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

После минификации исходный код становится практически нечитаемым:

Исходный код 

function calculateTotal(price, quantity) {
    const total = price * quantity;

    if (total > 1000) {
        console.log("Large order");
    }

    return total;
}

Минифицированный код 

function calculateTotal(t,o){const l=t*o;return l>1e3&&console.log("Large order"),l}

Если в продакшене возникнет ошибка, стек вызовов будет ссылаться именно на минифицированный файл. Анализ подобных ошибок без дополнительной информации крайне затруднителен.

Для решения этой проблемы используются source maps — специальные файлы сопоставления между оригинальным и преобразованным кодом.

Что представляет собой source map

Source map — это JSON-документ, содержащий информацию о том, какие участки итогового файла соответствуют строкам и столбцам исходного кода.

Типичный файл карты выглядит следующим образом: 

{
  "version": 3,
  "sources": [
    "src/index.js"
  ],
  "names": [
    "calculateTotal",
    "price",
    "quantity"
  ],
  "mappings": "AAAA..."
}

Основные поля:

Поле Назначение
version Версия формата source map
sources Список исходных файлов
names Имена переменных и функций
mappings Таблица соответствий
sourceRoot Базовый путь к исходникам
sourcesContent Содержимое исходных файлов

Браузеры используют эту информацию для восстановления первоначального кода во время отладки.

Поддержка source maps в SWC

SWC предоставляет встроенный механизм генерации source maps.

Простейшая конфигурация: 

const { transformFileSync } = require("@swc/core");

const result = transformFileSync("src/index.js", {
    minify: true,
    sourceMaps: true
});

Результат содержит два объекта: 

{
    code: "...",
    map: "..."
}
  • code — минифицированный JavaScript.
  • map — содержимое source map.

Варианты параметра sourceMaps

SWC поддерживает несколько режимов работы.

Генерация отдельного файла 

{
    sourceMaps: true
}

Создаётся отдельный файл карты: 

app.js
app.js.map

В конец итогового скрипта добавляется ссылка: 

//


Браузер автоматически загружает карту и использует её во время отладки.






Встраивание карты в файл



{
    sourceMaps: "inline"
}



В этом режиме карта кодируется в Base64 и помещается непосредственно в
JavaScript-файл.




Пример:



//# sourceMappingURL=dat a:application/json;base64,...



Преимущества:



    

  • 
отсутствие дополнительных файлов;

    • 

  • 
удобство локальной разработки.

    • 




Недостатки:



    

  • 
увеличение размера итогового бандла;

    • 

  • 
более медленная загрузка.

    • 






Исключение карт



{
    sourceMaps: false
}



Никакие карты не создаются.




Часто используется при сборке библиотек, когда разработчик не планирует
предоставлять исходники пользователям.






Минификация и сохранение соответствий




Во время минификации SWC выполняет множество преобразований:




Удаление пробелов




Исходник:



const message = "Hello World";



После минификации:



const message="Hello World";



Source map сохраняет информацию о позиции строки даже после удаления
пробельных символов.






Сжатие выражений




Исходный код:



if (isEnabled) {
    start();
}



Минифицированный вариант:



isEnabled&&start();



Несмотря на изменение структуры, карта содержит связь между обеими
версиями.






Переименование идентификаторов




Исходник:



function calculateTotalPrice(productPrice, amount) {
    return productPrice * amount;
}



После минификации:



function n(t,o){return t*o}



Source map хранит информацию о том, что:








Минифицированное имя


Исходное имя








n


calculateTotalPrice






t


productPrice






o


amount








Поэтому браузер способен показывать первоначальные названия переменных.






Настройка минификации с source maps




Распространённая конфигурация:



const { transformSync } = require("@swc/core");

const result = transformSync(sourceCode, {
    minify: true,
    sourceMaps: true,
    jsc: {
        target: "es2022"
    }
});



В данном случае:



    

  • 
код минифицируется;

    • 

  • 
создаётся карта соответствий;

    • 

  • 
сохраняется возможность отладки.

    • 






Использование через .swcrc




Настройка может быть вынесена в конфигурационный файл.



{
  "minify": true,
  "sourceMaps": true
}



При запуске SWC настройки будут применяться автоматически.






Структура mappings




Наиболее важным элементом source map является поле
mappings.




Пример:



{
  "mappings": "AAAA,SAASA..."
}



Строка содержит закодированные координаты:



    

  • 
номер строки;

    • 

  • 
номер столбца;

    • 

  • 
исходный файл;

    • 

  • 
исходную позицию;

    • 

  • 
имя символа.

    • 




Для уменьшения размера используется алгоритм:



    

  • 
Base64 VLQ Encoding;

    • 

  • 
относительные смещения вместо абсолютных координат.

    • 




Благодаря этому даже крупные карты занимают относительно небольшой
объём.






Связь source maps с DevTools




При открытии вкладки Sources в инструментах разработчика браузер
выполняет следующие действия:



    

  1. 
Загружает минифицированный файл.

    2. 

  2. 
Обнаруживает директиву sourceMappingURL.

    3. 

  3. 
Загружает карту.

    4. 

  4. 
Анализирует таблицу соответствий.

    5. 

  5. 
Восстанавливает оригинальную структуру проекта.

    6. 




Например:



//# sourceMappingURL=main.js.map



После загрузки карты в DevTools становятся доступны:



    

  • 
оригинальные файлы;

    • 

  • 
реальные номера строк;

    • 

  • 
настоящие имена функций;

    • 

  • 
корректные точки останова.

    • 






Работа breakpoints после минификации




Без source maps точка останова устанавливается в минифицированный код:



function a(b,c){return b+c}



Определить правильное место выполнения сложно.




С подключённой картой браузер отображает:



function add(first, second) {
    return first + second;
}



Breakpoint привязывается к исходному файлу, а не к минифицированной
версии.




Это делает отладку продакшен-сборок практически такой же удобной, как
работу с исходным кодом.






Отображение стеков ошибок




Рассмотрим ошибку:



TypeError: Cannot read properties of undefined
    at main.js:1:1245



Координаты:



Строка: 1
Столбец: 1245



Для минифицированного файла такая информация почти бесполезна.




После применения source map браузер может показать:



TypeError: Cannot read properties of undefined
    at src/services/user.js:45:18



Отладка становится значительно проще.






Source maps и системы мониторинга ошибок




Современные платформы отслеживания ошибок используют карты для
декодирования стеков.




Примеры:



    

  • 
Sentry

    • 

  • 
Rollbar

    • 

  • 
Bugsnag

    • 




Процесс выглядит следующим образом:



    

  1. 
Загружается минифицированная сборка.

    2. 

  2. 
Загружается соответствующий source map.

    3. 

  3. 
При возникновении ошибки сервис получает стек вызовов.

    4. 

  4. 
Координаты автоматически преобразуются в исходные строки проекта.

    5. 




В результате отчёты содержат оригинальный код, а не минифицированные
координаты.






Встраивание исходного содержимого




SWC способен помещать содержимое исходных файлов непосредственно в
карту.




Пример структуры:



{
  "sources": [
    "src/index.js"
  ],
  "sourcesContent": [
    "const message = 'Hello';"
  ]
}



Преимущества:



    

  • 
инструменты отладки могут показывать код даже без доступа к файлам
проекта;

    • 

  • 
упрощается анализ ошибок в сторонних сервисах.

    • 




Недостаток — увеличение размера карты.






SourceRoot




Параметр sourceRoot задаёт базовый каталог для исходников.




Пример:



{
  "sourceRoot": "/src"
}



Путь к файлу:



{
  "sources": [
    "components/App.js"
  ]
}



Будет интерпретирован как:



/src/components/App.js



Это особенно полезно в крупных монорепозиториях.






Производительность генерации карт




Создание source maps требует дополнительных вычислений.




Во время компиляции SWC должен:



    

  • 
отслеживать каждое преобразование;

    • 

  • 
сохранять координаты символов;

    • 

  • 
строить таблицу соответствий;

    • 

  • 
кодировать данные в формате VLQ.

    • 




Поэтому сборка с картами обычно выполняется медленнее, чем сборка без
них.




Особенно заметна разница при:



    

  • 
большом количестве модулей;

    • 

  • 
глубокой минификации;

    • 

  • 
генерации карт для нескольких выходных файлов.

    • 






Использование в разных окружениях




Разработка




Наиболее распространённый вариант:



{
  "sourceMaps": "inline"
}



Обеспечивается удобная локальная отладка без создания дополнительных
файлов.






Тестирование




Часто используется:



{
  "sourceMaps": true
}



Карты сохраняются отдельно и доступны средствам анализа ошибок.






Продакшен




Возможны несколько стратегий.




Публичные карты:



{
  "sourceMaps": true
}



Карты доступны браузеру пользователя.






Скрытые карты:



main.js
main.js.map



Файл карты хранится на сервере мониторинга и не публикуется вместе с
приложением.




Такой подход позволяет:



    

  • 
сохранять удобство диагностики;

    • 

  • 
не раскрывать исходный код пользователям.

    • 






Типичные проблемы




Несовпадение версий файлов




Если карта была создана для одной версии бандла, а загружен другой файл,
координаты станут неверными.




Например:



main.js      версия 15
main.js.map  версия 14



В результате отладка начнёт показывать неправильные строки.






Потеря sourceMappingURL




Некоторые инструменты постобработки удаляют директиву:



//# sourceMappingURL=main.js.map



Браузер перестаёт находить карту и работает только с минифицированным
кодом.






Повторная минификация




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




Пример цепочки:



SWC
  ↓
Минификация
  ↓
Source Map
  ↓
Дополнительный оптимизатор



Без объединения карт соответствия будут нарушены.






Комбинирование source maps в пайплайне сборки




В современных проектах код нередко проходит несколько стадий обработки:



TypeScript
    ↓
SWC
    ↓
Bundler
    ↓
Minifier



Каждый этап может создавать собственную карту.




Инструменты сборки объединяют их в единую цепочку соответствий, позволяя
связать финальный минифицированный файл с первоначальным
TypeScript-кодом.




Благодаря этому ошибка, возникшая в продакшен-бандле, может быть точно
сопоставлена с конкретной строкой исходного файла независимо от
количества промежуточных преобразований.
Оглавление