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

> https://docs.errora.org/products/source-maps

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

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

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

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

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

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

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

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

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

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

```bash
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 از [توکن دسترسی شخصی](/account/tokens) استفاده کنید — هرگز از توکن نشست یک کاربر.

### نمونهٔ GitLab CI

```yaml
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@${process.env.CI_COMMIT_SHORT_SHA}\`` بگذارید.

## ۴. بررسی

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

```text
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` هنگام بارگذاری | توکن ارسال نشده یا به آن پروژه دسترسی ندارد |