Что такое source map — и почему ошибка указывает на строку 1, символ 48213

Смотри, что бывает после первого деплоя. Пользователь пишет: «кнопка не работает». Ты открываешь консоль, а там ошибка в файле index-a8f3c.js, строка 1, символ 48213.

Весь твой сайт после сборки — одна строка длиной в сотни тысяч символов. Имена функций сжаты до a, b, t. Искать по такому адресу бесполезно. Вот для этого и придумали source map.

Что такое source map

Source map (карта исходников) — это файл-словарь, который связывает каждое место в собранном коде с местом в твоём исходном. «Строка 1, символ 48213» → «Cart.tsx, строка 42, функция addToCart».

Собранный код нужен браузеру: он маленький и быстро грузится. Исходный нужен тебе: его можно читать. Карта — мост между ними.

Она лежит рядом с бандлом и обычно называется так же, но с .map: index-a8f3c.js.map. А в конце самого бандла стоит комментарий-указатель:

//# sourceMappingURL=index-a8f3c.js.map

С конца 2024 года формат карт описан официальным стандартом ECMA-426. До этого все жили по неформальному документу, который сложился ещё в 2011-м.

Как она работает

Внутри .map — обычный JSON. Самые важные поля:

• sources — список твоих исходных файлов: src/Cart.tsx, src/api.ts.
• mappings — длинная закодированная строка. Это и есть сама карта: «вот этот кусок сжатого кода пришёл вот отсюда».
• names — настоящие имена переменных, которые сборщик сжал до одной буквы.
• sourcesContent — часто там лежит полный текст твоих исходников. Запомни это поле, оно ещё всплывёт.

Ты эту строку mappings никогда не читаешь сам. Её читает браузер. Открываешь DevTools — и он сам находит карту по комментарию, скачивает её и показывает ошибку в твоём файле. С нормальными именами и номерами строк. Даже точки останова можно ставить в исходнике.

Так же работают сервисы отлова ошибок вроде Sentry. Они берут сжатый стек вызовов от пользователя и разворачивают его по карте в понятный.

Вот как это выглядит на деле. Без карты:

TypeError: Cannot read properties of undefined (reading 'price')
    at t (index-a8f3c.js:1:48213)

С картой та же ошибка:

TypeError: Cannot read properties of undefined (reading 'price')
    at addToCart (src/Cart.tsx:42:18)

Одна строчка разницы — и вместо часа поисков ты сразу открываешь нужный файл. Это особенно ценно, когда код писал ИИ и ты не помнишь, где что лежит.

Подвох: карта — это твой исходный код

Вспомни поле sourcesContent. Если карта лежит на сервере открыто, любой посетитель может открыть DevTools и увидеть твой проект целиком. Все файлы, комментарии, названия внутренних функций.

Это не теория. 31 марта 2026 года в npm-пакет Claude Code случайно попал файл cli.js.map на десятки мегабайт. По разборам, из него восстановили почти две тысячи исходных файлов самого инструмента. Код разошёлся по GitHub за часы.

Важное уточнение: исходник на фронтенде всё равно не секрет. Браузер всегда получает твой JavaScript, просто сжатым. Поэтому настоящие секреты вроде ключей вообще не должны попадать во фронтенд — про это отдельная статья. Карта не создаёт дыру, но делает чтение кода в сто раз проще.

Как настроить в своём проекте

Большинство сборщиков по умолчанию не выкладывают карты в продакшен. Проверь, что так и осталось:

• Vite — build.sourcemap по умолчанию false. Вариант 'hidden' создаёт карты, но не пишет комментарий-указатель в бандл: браузер о них не узнает.
• Next.js — карты для браузера в продакшене выключены, пока ты не включил productionBrowserSourceMaps.

Золотая середина для живого проекта: собирать карты, отправлять их в сервис ошибок и удалять из папки сборки до деплоя. Sentry умеет это одной настройкой при загрузке. Ты получаешь понятные ошибки, а посетители — только сжатый код.

Проверка за 10 секунд: открой свой сайт, возьми адрес любого .js из вкладки Network и допиши к нему .map. Если скачался JSON — карты открыты.

Нужна ли source map в режиме разработки?

Да, и там она включена сама. pnpm dev в Vite или Next.js отдаёт карты всегда — поэтому в разработке ошибки показывают нормальные строки, а после сборки внезапно нет.

Замедляют ли карты сайт?

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

Как прочитать ошибку, если карты нет?

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