Next.js — خرائط المصدر

مقدمة

تكون بناءات Next.js للإنتاج مُصغَّرة (minified)، لذا يبدو تتبّع المكدس (stack trace) القادم من مستخدم حقيقي هكذا:

onConnMessage@https://app.example.com/_next/static/chunks/app/page-Cr8GYWvZ.js:10:14780

عندما ترفع خرائط المصدر (source maps) الخاصة ببنائك إلى Lerix، تعيد لوحة التحكم كل إطار إلى كودك الأصلي، مثل app/chat/page.tsx:142، وتعرض الأسطر المحيطة به. تُرفَع الخرائط بشكل خاص وتُحذف من مخرجات البناء قبل النشر. لا تُقدَّم علناً أبداً، لذا يبقى كودك المصدري خاصاً.

أكمِل تثبيت Next.js أولاً. يتطلّب تعيين الإصدار (release) الحزمة @lerix-dev/lerix-core بالإصدار 1.1.0 أو أحدث.

1. فعّل خرائط المصدر للمتصفح

فعّل خرائط المصدر للمتصفح في بناء الإنتاج ضمن إعدادات Next.js:

next.config.ts

import type { NextConfig } from 'next';

const nextConfig: NextConfig = {
  productionBrowserSourceMaps: true,
};

export default nextConfig;

شغّل next build وتأكّد من ظهور ملفات .js.map داخل .next/static/chunks.

يضيف Next.js تعليق //# sourceMappingURL إلى ملفات JavaScript المنشورة. هذا لا يضر: تحذف الأداة الخرائط قبل النشر، فيشير التعليق ببساطة إلى ملف يعيد 404.

2. أنشئ مفتاح API خاصاً

يحتاج رفع خرائط المصدر إلى مفتاح خاص، منفصل عن مفتاح المشروع العام الذي يستخدمه تطبيقك.

افتح مشروعك في لوحة تحكم Lerix.
اذهب إلى Project settings ← API keys.
أنشئ مفتاحاً بصلاحية Upload source maps (أو Full access).

هذا المفتاح سرّي. خزّنه كسرّ (secret) في نظام CI ولا تضعه أبداً في كود العميل أو في متغير يبدأ بـ NEXT_PUBLIC_ أو في مستودعك.

3. ارفع الخرائط بعد كل بناء

بعد next build وقبل النشر، شغّل أداة Lerix CLI على المجلد .next:

npx @lerix-dev/lerix-cli upload

شغّلها من مجلد مشروعك. تجد الأداة مخرجات البناء تلقائياً (.next) وتستخدم version من package.json كإصدار. ولتحديدهما بنفسك: npx @lerix-dev/lerix-cli upload .next --release 1.4.0. تجد الأداة الخرائط داخل .next/static/chunks، وترفع كل ملف *.js.map (وتتجاهل node_modules وخرائط CSS)، ثم تحذف ملفات .map من مخرجات البناء كي لا تُنشر أبداً. إذا فشل أي رفع، تُبقي الأداة الخرائط وتخرج بالرمز 1، لتتمكّن من إعادة الخطوة. تتطلّب الأداة Node.js بالإصدار 18.17 أو أحدث. إذا كان مزوّد الاستضافة يشغّل البناء نيابةً عنك، فشغّل الرفع ضمن أمر البناء نفسه ليحدث قبل نشر المخرجات، مثل next build && npx @lerix-dev/lerix-cli upload.

الرفع مع كل بناء

بدلاً من تشغيل الأمر بنفسك، ثبّت الأداة في مشروعك واجعل npm يشغّلها بعد كل بناء:

npm install --save-dev @lerix-dev/lerix-cli

package.json

"scripts": {
  "build": "next build",
  "postbuild": "lerix upload --optional"
}

الآن كل npm run build يرفع الخرائط. الخيار --optional يُبقي البناء المحلي يعمل: على جهاز لا يحوي LERIX_SECRET_KEY (جهاز المطوّر)، يُتخطّى الرفع بدلاً من إفشال البناء، مع حذف ملفات .map كالمعتاد. عيّن المفاتيح في نظام الـ CI أو خادم البناء حيث يُنفَّذ بناء الإنتاج.

لا يشغّل pnpm ولا Yarn 2+ سكربتات postbuild. اربط الأمر بدلاً من ذلك: "build": "next build && lerix upload --optional".

الخيارات

يمكن تعيين كل خيار أيضاً عبر متغير بيئة.

الخيار	متغير البيئة	الوصف
`--release`	`LERIX_RELEASE`	الإصدار الذي يُنشر به هذا البناء. الافتراضي هو `version` في `package.json`. مرّر القيمة نفسها إلى الـ SDK (راجع الخطوة 4)
`--api-key`	`LERIX_API_KEY`	مفتاح API العام المعتاد لمشروعك
`--project-id`	`LERIX_PROJECT_ID`	معرّف مشروعك
`--secret-key`	`LERIX_SECRET_KEY`	المفتاح الخاص من الخطوة 2
`--url`	`LERIX_URL`	رابط Lerix API. القيمة الافتراضية `https://api.lerix.dev/v1`
`--keep-maps`		إبقاء ملفات `.map` في مخرجات البناء بدلاً من حذفها
`--dry-run`		عرض الخرائط التي سترفع دون رفع أي شيء
`--optional`		تخطّي الرفع بدلاً من الفشل عند عدم تعيين المفاتيح (البناء المحلي). تُحذف ملفات `.map` مع ذلك

4. مرّر الإصدار نفسه إلى الـ SDK

عيّن NEXT_PUBLIC_LERIX_RELEASE إلى القيمة التي مرّرتها إلى --release، وسيقرؤه LerixNextProvider تلقائياً:

.env.local

NEXT_PUBLIC_LERIX_RELEASE=1.4.0

أو مرّر release صراحةً ضمن options:

<LerixNextProvider options={{ release: '1.4.0' }}>

يطابق Lerix الخرائط حسب اسم ملف السكربت. أسماء أجزاء (chunks) Next.js مشتقّة من محتواها (content-hashed)، لذا فهي فريدة لكل بناء، ويفضّل Lerix الخرائط من الإصدار نفسه. تظل المطابقة تعمل إذا حذفت release، لكن يُنصح بتعيينه. كما يحلّ الإصدار محلّ رقم الإصدار 0.0.0 الذي كان يظهر سابقاً لتطبيقات الويب.

استخدم القيمة نفسها في الموضعين دون تعديلها يدوياً: معرّف commit في git أو قيمة version من package.json كلاهما خيار جيد.

مثال: GitHub Actions

يبني سير العمل هذا التطبيق، ثم يرفع الخرائط، ثم ينشر. أضِف LERIX_API_KEY وLERIX_PROJECT_ID وLERIX_SECRET_KEY كأسرار (secrets) في المستودع.

.github/workflows/deploy.yml

jobs:
  deploy:
    runs-on: ubuntu-latest
    env:
      LERIX_RELEASE: ${{ github.sha }}
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 20
      - run: npm ci

      # Make the same release available to the app at build time
      - run: npx next build
        env:
          NEXT_PUBLIC_LERIX_RELEASE: ${{ github.sha }}

      - run: npx @lerix-dev/lerix-cli upload
        env:
          LERIX_API_KEY: ${{ secrets.LERIX_API_KEY }}
          LERIX_PROJECT_ID: ${{ secrets.LERIX_PROJECT_ID }}
          LERIX_SECRET_KEY: ${{ secrets.LERIX_SECRET_KEY }}

      # Deploy the build here. .next no longer contains .map files.

ما تراه في لوحة التحكم

تعرض الأخطاء الجديدة الملف والسطر والدالة الأصلية، مع الكود المحيط. انقر Show minified لرؤية المكدس كما أرسله المتصفح تماماً. يتلقّى المساعد الذكي وقضايا GitHub وخادم MCP جميعهم المكدس المقروء أيضاً.

لا تُحوَّل إلا الأخطاء المُبلَّغ عنها بعد رفع الخرائط. تبقى الأخطاء الأقدم بمكدسها المُصغَّر.
يحتفظ Lerix بأحدث 5,000 خريطة لكل مشروع.
الحد الأقصى لحجم الخريطة الواحدة 50 MB.

استكشاف الأخطاء وإصلاحها

المشكلة	الحل
`no .js.map files found`	خرائط المصدر للمتصفح غير مفعّلة. راجع `productionBrowserSourceMaps` في الخطوة 1 وتأكّد من توجيه الأداة إلى المجلد `.next`.
`Uploading source maps needs a private API key...` (`SOURCE_MAP_SECRET_KEY_MISSING`)	الخيار `--secret-key` مفقود أو غير صالح. أنشئ مفتاحاً خاصاً كما في الخطوة 2.
`PROJECT_API_KEY_DONT_HAVE_PERMISSION`	المفتاح الخاص لا يملك صلاحية Upload source maps. عدّل المفتاح أو أنشئ مفتاحاً جديداً بهذه الصلاحية.
لا يزال المكدس مُصغَّراً	تأكّد من تطابق `release` في الـ SDK مع `--release`، ومن رفع خرائط هذا البناء بالتحديد، ومن أن الخطأ جديد. كل إعادة بناء تغيّر بصمات الأجزاء (chunk hashes)، لذا ارفع الخرائط مجدداً بعد كل بناء.

البدء

أطر العمل

الوحدات

المطورون

Next.js — خرائط المصدر

مقدمة

1. فعّل خرائط المصدر للمتصفح

2. أنشئ مفتاح API خاصاً

3. ارفع الخرائط بعد كل بناء

الرفع مع كل بناء

الخيارات

4. مرّر الإصدار نفسه إلى الـ SDK

مثال: GitHub Actions

ما تراه في لوحة التحكم

استكشاف الأخطاء وإصلاحها

​مقدمة

​1. فعّل خرائط المصدر للمتصفح

​2. أنشئ مفتاح API خاصاً

​3. ارفع الخرائط بعد كل بناء

​الرفع مع كل بناء

​الخيارات

​4. مرّر الإصدار نفسه إلى الـ SDK

​مثال: GitHub Actions

​ما تراه في لوحة التحكم

​استكشاف الأخطاء وإصلاحها

مقدمة

1. فعّل خرائط المصدر للمتصفح

2. أنشئ مفتاح API خاصاً

3. ارفع الخرائط بعد كل بناء

الرفع مع كل بناء

الخيارات

4. مرّر الإصدار نفسه إلى الـ SDK

مثال: GitHub Actions

ما تراه في لوحة التحكم

استكشاف الأخطاء وإصلاحها