Source maps и релизы фронтенда

Продакшен-сборка фронтенда минифицирована, поэтому без source maps стек ошибки выглядит как at Xe (index-B3x9.js:1:48211) — понятно только, что что-то сломалось. Когда сборка загружает source maps в NablOps, та же ошибка показывается по исходному коду: at renderCard (src/app/StackCard.tsx:42:7), с кодом вокруг строки, а для упавшего компонента React — где в ваших компонентах это случилось.

Карты загружаются при сборке и в бандл не попадают: посетители сайта их не видят. Ниже — как подключить загрузку для Vite и других сборщиков, как обойтись без секретов в CI и что показывает вкладка «Релизы».

Зачем source maps для ошибок фронтенда

  • Стек по исходникам. Файл, функция, строка и код вокруг неё вместо строки минифицированного бандла.
  • Компоненты React. Стек компонентов из ErrorBoundary тоже переводится в файлы и строки исходников.
  • Точная группировка. С картами одна ошибка в Chrome, Safari и Firefox — одна запись: учитываются функции и файлы вашего кода, а не текст сообщения, который у каждого браузера свой. Подробнее — в статье ошибки фронтенда на React.

Если карт для релиза нет, на странице ошибки появляется пометка «Нет source map для релиза …», а в покрытии проекта — шаг «Нет source maps у релиза …».

Как загружать source maps в Vite

bash
npm install -D @nablops/vite-plugin
ts
// vite.config.ts
import { defineConfig } from 'vite';
import react from '@vitejs/plugin-react';
import { nablops } from '@nablops/vite-plugin';

export default defineConfig({
  plugins: [react(), nablops()],
});

При каждой сборке плагин:

  1. Определяет релиз: опция release, иначе переменная NABL_RELEASE, иначе короткий хэш коммита git, иначе время сборки. Релиз попадает в бандл, поэтому в init его передавать не нужно.
  2. Включает скрытые карты (build.sourcemap: 'hidden'), если вы не задали sourcemap сами: карты собираются, но ссылки на них в бандле нет.
  3. Вписывает debug id в каждый чанк и его карту. По нему NablOps находит нужную карту, даже если файлы лежат на CDN или имена повторяются в разных релизах. Номера строк и колонок в стеке остаются верными.
  4. Загружает карты в NablOps и при сбое сети повторяет до 3 раз.
  5. Удаляет .map из dist — на прод карты не уезжают. Карты, которые вы включили сами как sourcemap: true, остаются на месте.

Если загрузка не удалась, плагин пишет предупреждение в лог сборки, а сборка завершается успешно. Чтобы она падала, включите failOnError: true. Без авторизации — например, при локальной сборке — плагин пишет одну строку в лог и ничего не загружает.

Опция По умолчанию Что задаёт
release NABL_RELEASE → git → время версия сборки
token NABL_UPLOAD_TOKEN токен загрузки; не нужен при доверенной сборке
frontendId NABL_FRONTEND_ID фронтенд, в котором отметить выкладку
commit NABL_COMMIT или текущий коммит коммит для отметки выкладки
deleteMaps true удалять ли загруженные карты из dist
failOnError false ронять ли сборку при неудачной загрузке

CLI nablops для webpack, esbuild и других сборщиков

Для любого другого сборщика есть команда nablops (Node.js 18+):

bash
npm install -D @nablops/cli
bash
export NABL_RELEASE=$(git rev-parse --short HEAD)

npm run build                     # сборщик должен сохранить .map рядом с .js
npx nablops sourcemaps inject ./dist --release "$NABL_RELEASE"
npx nablops sourcemaps upload ./dist --release "$NABL_RELEASE" --delete-maps
# … выкладка …
npx nablops releases deploy --frontend <id фронтенда> --release "$NABL_RELEASE" --commit "$CI_COMMIT_SHA"
  • inject вписывает debug id в .js, .mjs и .cjs и их карты. Запускайте его после сборки и до загрузки; на сервер должны уехать файлы уже после inject.
  • upload загружает все .map каталога; --delete-maps удаляет успешно загруженные. Карты больше 50 МБ пропускаются. Если хоть одна карта не загрузилась, команда завершается с кодом 1.
  • releases deploy отмечает выкладку релиза во фронтенде.

Тот же релиз передайте в init опцией release — у Next.js и webpack мастер подключения показывает строку с переменной сборки.

Доверенная сборка: source maps без секретов в CI

Хранить токен в CI не нужно. Сборка в GitLab CI или GitHub Actions сама подтверждает, откуда она: предъявляет OIDC-токен своего CI, NablOps проверяет подпись провайдера, репозиторий и ветку и выдаёт плагину короткий токен загрузки на 30 минут. Украсть нечего: токен из лога через полчаса бесполезен, а сборке из другого репозитория NablOps его не выдаст. Нужен @nablops/vite-plugin или @nablops/cli 0.2.0 и новее.

Как настроить:

  1. Откройте фронтенд → вкладка «Настройки» → карточка «Source maps — стек по исходникам» → «Доверенная сборка».
  2. Выберите, где идёт сборка — «GitLab CI» (для своего GitLab — его адрес) или «GitHub Actions», укажите репозиторий (group/project или owner/repo) и ветку, из которой выкатывается это окружение. Нажмите «Доверять сборке».
  3. Добавьте в CI фрагмент, который там же показан.

GitLab CI — в job сборки:

yaml
build:
  id_tokens:
    NABL_ID_TOKEN:
      aud: https://app.nablops.io

GitHub Actions — в workflow:

yaml
permissions:
  id-token: write
  contents: read

После первой сборки в карточке правила видно, когда сборка получила токен и сколько карт загружено для какого релиза. Если сборка получила токен, но карт не загрузила, причина — в строке [nablops] лога сборки.

Сборка внутри docker build. Окружение CI в неё само не попадает. Передайте OIDC-токен секретом BuildKit — в слои образа он не попадёт: docker build --secret id=nabl_id_token,env=NABL_ID_TOKEN --build-arg NABL_CI_JOB=$CI_JOB_ID …, а в Dockerfile — ARG NABL_CI_JOB= и RUN --mount=type=secret,id=nabl_id_token,env=NABL_ID_TOKEN echo $NABL_CI_JOB && npm run build. NABL_CI_JOB нужен, потому что секрет не входит в ключ кэша Docker: без него перезапуск сборки того же коммита возьмёт шаг из кэша и карты не загрузит.

Токен загрузки для других CI

Для Jenkins и сборок вне CI остаётся токен загрузки: в тех же настройках — «Другой CI (Jenkins, сборка вне CI) — токен загрузки». Токен nabl_up_… показывается один раз и действует для всех фронтендов вашего аккаунта. Положите его в секрет CI NABL_UPLOAD_TOKEN. Если заданы и токен, и доверенная сборка, используется токен.

Вкладка «Релизы»

На вкладке «Релизы» фронтенда — все версии сборки:

Колонка Что показывает
«Релиз» версия и когда пришли первые события; у последней — пометка «свежий»
«Выкладка» когда выложена и с каким коммитом, или «не отмечена»
«Source maps» сколько карт загружено, или «нет карт» — стек ошибок этого релиза по минифицированному бандлу
«Новых ошибок» ошибки, впервые появившиеся в этом релизе
«Повторов» сколько раз ошибки случались в релизе

Выкладки в ленте. Выкладку отмечает плагин (опция frontendId) или команда nablops releases deploy: в ленте фронтенда появляется событие, на графиках — маркер. Если одна сборка сначала едет на staging, а потом на prod, отмечайте выкладку на шаге деплоя командой CLI, а не в сборке. Без отметки выкладкой считается первое событие с новым релизом.

Регресс в релизе. Если ошибка, которую отметили решённой, вернулась, на её странице видно, в каком релизе она снова появилась. Новые ошибки свежего релиза видны в колонке «Новых ошибок» сразу после выкладки, а падение стабильности — на «Обзоре» в разбивке по релизам.

Карта, загруженная уже после первых ошибок релиза, подхватывается в течение минуты: следующий повтор ошибки переводится по исходникам. Карты хранятся 180 дней с загрузки.

Настройка через ИИ-ассистента

ИИ-ассистент настраивает загрузку карт от начала до конца: подключает плагин, создаёт правило доверенной сборки для вашего репозитория и ветки, вписывает фрагмент в CI и после сборки проверяет, что карты дошли. Для CI без OIDC он создаст токен загрузки.

Что дальше

Попробуйте NablOps

Первый сервер или стек подключается за пару минут. Бесплатно в раннем доступе.

Создать аккаунт

Нашли неточность или не хватает ответа? Напишите в поддержку