سورس‌مپ و نسخه‌ها

بدون سورس‌مپ، ردپای خطای مرورگر چیزی شبیه app.4f2c.js:1:28461 است. با سورس‌مپ می‌شود src/checkout/pay.ts:88، همراه با خطوط اطراف.

ارورا پیش از گروه‌بندی نمادگشایی می‌کند، پس خطاها روی فریم‌های اصلی و پایدار گروه می‌شوند نه روی هش باندلی که هر بار استقرار عوض می‌شود.

۱. تولید سورس‌مپ

// vite.config.ts
export default defineConfig({ build: { sourcemap: true } });

// webpack.config.js
module.exports = { devtool: "source-map" };

در Next.js: productionBrowserSourceMaps: true در next.config.js.

۲. تعیین نسخه در SDK

رشتهٔ نسخه، کلیدی است که همه‌چیز زیر آن بایگانی می‌شود و باید دقیقاً میان SDK و بارگذاری یکسان باشد.

Sentry.init({
  dsn: "…",
  release: "web@1.4.2",     // همان رشته‌ای که پایین بارگذاری می‌شود
  dist: "prod",             // اختیاری، برای پلتفرم‌هایی که چند توزیع می‌سازند
});

۳. بارگذاری فایل‌ها از CI

for map in dist/assets/*.js.map; do
  curl -sf -X POST "$ERRORA/api/v1/projects/$PROJECT_ID/release-files" \
    -H "Authorization: Bearer $ERRORA_TOKEN" \
    -F "release=web@1.4.2" \
    -F "name=~/assets/$(basename "${map%.map}")" \
    -F "sourcemap=1" \
    -F "file=@$map"
done

فیلد	معنی
release	اجباری. باید برابر release در SDK باشد.
name	اجباری. مسیر آدرس فایل. ~/ یعنی «هر میزبانی» که معمولاً همان چیزی است که می‌خواهید.
dist	برچسب توزیع اختیاری؛ باید با dist در SDK یکی باشد.
sourcemap	مشخص می‌کند این بارگذاری نقشه است نه باندل.
file	خود فایل، به شکل multipart/form-data.

بارگذاری دوبارهٔ همان سه‌تایی (release, dist, name) جایگزین قبلی می‌شود، پس اجرای دوبارهٔ استقرار بی‌خطر است.

برای CI از توکن دسترسی شخصی استفاده کنید — هرگز از توکن نشست یک کاربر.

نمونهٔ GitLab CI

upload-sourcemaps:
  stage: deploy
  script:
    - npm run build
    - |
      for map in dist/assets/*.js.map; do
        curl -sf -X POST "$ERRORA/api/v1/projects/$PROJECT_ID/release-files" \
          -H "Authorization: Bearer $ERRORA_TOKEN" \
          -F "release=web@$CI_COMMIT_SHORT_SHA" \
          -F "name=~/assets/$(basename "${map%.map}")" \
          -F "sourcemap=1" -F "file=@$map"
      done

…و در Sentry.init هم release: \web@$`` بگذارید.

۴. بررسی

در بیلد مستقرشده خطایی ایجاد کنید و صفحهٔ خطا را باز کنید. فریم‌ها باید فایل، خط، ستون و کد اصلی شما را نشان دهند. فهرست فایل‌های بارگذاری‌شده اینجاست:

GET    /api/v1/projects/{project_id}/release-files?release=web@1.4.2&dist=
POST   /api/v1/projects/{project_id}/release-files
GET    /api/v1/projects/{project_id}/release-files/{id}
DELETE /api/v1/projects/{project_id}/release-files/{id}

چطور کار می‌کند

ارورا برای هر فریم مینیفای‌شده، فایل مربوطه را با نام پیدا می‌کند، از روی نقشه به فایل، خط و ستون اصلی می‌رسد و اگر نقشه sourcesContent داشته باشد، خطوط کد اطراف را هم پیوست می‌کند. sourcesContent را در نقشه‌هایتان نگه دارید: بدون آن نام فایل و شماره خط درست را دارید، اما متن کد را نه.

آیا نقشه‌ها باید عمومی باشند؟

نه. آن‌ها را به ارورا بفرستید و فایل‌های .map را روی وب‌سرور خود منتشر نکنید (یا پشت احراز هویت بگذارید). ارورا آن‌ها را سمت سرور می‌خواند؛ کاربران شما هیچ‌وقت به آن‌ها نیاز ندارند.

عیب‌یابی

نشانه	علت / راه‌حل
فریم‌ها هنوز مینیفای‌اند	ناهماهنگی release میان SDK و بارگذاری — شایع‌ترین علت
فایل درست است ولی کد نشان داده نمی‌شود	نقشه sourcesContent ندارد
بعضی فریم‌ها حل می‌شوند و بعضی نه	فقط بخشی از باندل‌ها بارگذاری شده‌اند؛ روی همهٔ نقشه‌ها از جمله چانک‌های vendor حلقه بزنید
شماره خط‌ها اشتباه است	نقشهٔ بارگذاری‌شده مربوط به بیلد دیگری است — از همان جاب CI که بیلد را ساخته بارگذاری کنید
پاسخ 401 هنگام بارگذاری	توکن ارسال نشده یا به آن پروژه دسترسی ندارد