logoNext.js العربية
التوثيقالمدونةالتعلم
مقدمة/أدلة/التصحيح

كيفية استخدام أدوات التصحيح مع Next.js

يشرح هذا التوثيق كيف يمكنك تصحيح كود الواجهة الأمامية والخلفية لتطبيق Next.js مع دعم كامل لخرائط المصدر باستخدام مصحح VS Code، أو Chrome DevTools، أو Firefox DevTools.

أي مصحح يمكنه الاتصال بـ Node.js يمكن أيضًا استخدامه لتصحيح تطبيق Next.js. يمكنك العثور على مزيد من التفاصيل في دليل تصحيح Node.js.

التصحيح باستخدام VS Code

قم بإنشاء ملف باسم .vscode/launch.json في جذر مشروعك بالمحتوى التالي:

launch.json
{
  "version": "0.2.0",
  "configurations": [
    {
      "name": "Next.js: تصحيح جانب الخادم",
      "type": "node-terminal",
      "request": "launch",
      "command": "npm run dev"
    },
    {
      "name": "Next.js: تصحيح جانب العميل",
      "type": "chrome",
      "request": "launch",
      "url": "http://localhost:3000"
    },
    {
      "name": "Next.js: تصحيح جانب العميل (Firefox)",
      "type": "firefox",
      "request": "launch",
      "url": "http://localhost:3000",
      "reAttach": true,
      "pathMappings": [
        {
          "url": "webpack://_N_E",
          "path": "${workspaceFolder}"
        }
      ]
    },
    {
      "name": "Next.js: تصحيح المكدس الكامل",
      "type": "node",
      "request": "launch",
      "program": "${workspaceFolder}/node_modules/next/dist/bin/next",
      "runtimeArgs": ["--inspect"],
      "skipFiles": ["<node_internals>/**"],
      "serverReadyAction": {
        "action": "debugWithEdge",
        "killOnServerStop": true,
        "pattern": "- Local:.+(https?://.+)",
        "uriFormat": "%s",
        "webRoot": "${workspaceFolder}"
      }
    }
  ]
}

ملاحظة: لاستخدام تصحيح Firefox في VS Code، ستحتاج إلى تثبيت امتداد Firefox Debugger.

يمكن استبدال npm run dev بـ yarn dev إذا كنت تستخدم Yarn أو pnpm dev إذا كنت تستخدم pnpm.

في تكوين "Next.js: تصحيح المكدس الكامل"، يحدد serverReadyAction.action أي متصفح سيتم فتحه عندما يكون الخادم جاهزًا. debugWithEdge يعني تشغيل متصفح Edge. إذا كنت تستخدم Chrome، قم بتغيير هذه القيمة إلى debugWithChrome.

إذا كنت تغير رقم المنفذ الذي يبدأ عليه تطبيقك، استبدل 3000 في http://localhost:3000 بالمنفذ الذي تستخدمه بدلاً من ذلك.

إذا كنت تقوم بتشغيل Next.js من دليل غير الجذر (على سبيل المثال، إذا كنت تستخدم Turborepo) فأنت بحاجة إلى إضافة cwd إلى مهام تصحيح جانب الخادم والمكدس الكامل. على سبيل المثال، "cwd": "${workspaceFolder}/apps/web".

الآن انتقل إلى لوحة التصحيح (Ctrl+Shift+D في Windows/Linux، ⇧+⌘+D في macOS)، حدد تكوين الإطلاق، ثم اضغط F5 أو حدد Debug: Start Debugging من لوحة الأوامر لبدء جلسة التصحيح الخاصة بك.

استخدام المصحح في Jetbrains WebStorm

انقر على القائمة المنسدلة التي تعرض تكوين التشغيل، وانقر على Edit Configurations.... أنشئ تكوين تصحيح JavaScript Debug مع http://localhost:3000 كعنوان URL. قم بتخصيصه حسب رغبتك (مثل المتصفح للتصحيح، تخزينه كملف مشروع)، وانقر على OK. قم بتشغيل تكوين التصحيح هذا، ويجب أن يفتح المتصفح المحدد تلقائيًا. في هذه المرحلة، يجب أن يكون لديك تطبيقان في وضع التصحيح: تطبيق NextJS node، وتطبيق العميل/المتصفح.

التصحيح باستخدام أدوات مطوري المتصفح

كود جانب العميل

ابدأ خادم التطوير الخاص بك كالمعتاد عن طريق تشغيل next dev، أو npm run dev، أو yarn dev. بمجرد بدء الخادم، افتح http://localhost:3000 (أو عنوان URL البديل الخاص بك) في متصفحك المفضل.

لـ Chrome:

  • افتح أدوات مطوري Chrome (Ctrl+Shift+J في Windows/Linux، ⌥+⌘+I في macOS)
  • انتقل إلى علامة التبويب Sources

لـ Firefox:

  • افتح أدوات مطوري Firefox (Ctrl+Shift+I في Windows/Linux، ⌥+⌘+I في macOS)
  • انتقل إلى علامة التبويب Debugger

في أي من المتصفحين، في أي وقت يصل كود جانب العميل الخاص بك إلى عبارة debugger، سيتم إيقاف تنفيذ الكود وسيظهر هذا الملف في منطقة التصحيح. يمكنك أيضًا البحث عن الملفات لتعيين نقاط التوقف يدويًا:

  • في Chrome: اضغط Ctrl+P في Windows/Linux أو ⌘+P في macOS
  • في Firefox: اضغط Ctrl+P في Windows/Linux أو ⌘+P في macOS، أو استخدم شجرة الملفات في اللوحة اليسرى

لاحظ أنه عند البحث، سيكون لملفات المصدر الخاصة بك مسارات تبدأ بـ webpack://_N_E/./.

كود جانب الخادم

لتصحيح كود Next.js الخاص بجانب الخادم باستخدام أدوات مطوري المتصفح، تحتاج إلى تمرير علم --inspect إلى عملية Node.js الأساسية:

Terminal
NODE_OPTIONS='--inspect' next dev

معلومة مفيدة: استخدم NODE_OPTIONS='--inspect=0.0.0.0' للسماح بالوصول إلى التصحيح عن بُعد خارج localhost، مثل عند تشغيل التطبيق في حاوية Docker.

إذا كنت تستخدم npm run dev أو yarn dev فيجب عليك تحديث سكريبت dev في ملف package.json الخاص بك:

package.json
{
  "scripts": {
    "dev": "NODE_OPTIONS='--inspect' next dev"
  }
}

سيبدو تشغيل خادم التطوير Next.js مع علم --inspect كالتالي:

Terminal
Debugger listening on ws://127.0.0.1:9229/0cf90313-350d-4466-a748-cd60f4e47c95
For help, see: https://nodejs.org/en/docs/inspector
ready - started server on 0.0.0.0:3000, url: http://localhost:3000

لـ Chrome:

  1. افتح علامة تبويب جديدة وزر chrome://inspect
  2. انقر على Configure... للتأكد من إدراج منافذ التصحيح
  3. أضف كل من localhost:9229 و localhost:9230 إذا لم يكونا موجودين بالفعل
  4. ابحث عن تطبيق Next.js الخاص بك في قسم Remote Target
  5. انقر على inspect لفتح نافذة منفصلة لأدوات المطور
  6. انتقل إلى علامة التبويب Sources

لـ Firefox:

  1. افتح علامة تبويب جديدة وزر about:debugging
  2. انقر على This Firefox في الشريط الجانبي الأيسر
  3. تحت Remote Targets، ابحث عن تطبيق Next.js الخاص بك
  4. انقر على Inspect لفتح المصحح
  5. انتقل إلى علامة التبويب Debugger

يعمل تصحيح كود جانب الخادم بشكل مشابه لتصحيح جانب العميل. عند البحث عن الملفات (Ctrl+P/⌘+P)، سيكون لملفات المصدر الخاصة بك مسارات تبدأ بـ webpack://{application-name}/./ (حيث سيتم استبدال {application-name} باسم تطبيقك وفقًا لملف package.json الخاص بك).

فحص أخطاء الخادم باستخدام أدوات مطوري المتصفح

عندما تواجه خطأً، يمكن أن يساعد فحص الكود المصدري في تتبع السبب الجذري للأخطاء.

سيقوم Next.js بعرض أيقونة Node.js أسفل مؤشر إصدار Next.js على نافذة الخطأ. بالنقر على هذه الأيقونة، يتم نسخ عنوان URL لأدوات المطور إلى الحافظة الخاصة بك. يمكنك فتح علامة تبويب جديدة في المتصفح باستخدام هذا العنوان URL لفحص عملية خادم Next.js.

التصحيح على Windows

قد يواجه مستخدمو Windows مشكلة عند استخدام NODE_OPTIONS='--inspect' لأن هذا التركيب غير مدعوم على منصات Windows. للتحايل على هذا، قم بتثبيت حزمة cross-env كاعتماد تطوير (-D مع npm و yarn) واستبدل سكريبت dev بما يلي.

package.json
{
  "scripts": {
    "dev": "cross-env NODE_OPTIONS='--inspect' next dev"
  }
}

سيقوم cross-env بتعيين متغير البيئة NODE_OPTIONS بغض النظر عن المنصة التي تستخدمها (بما في ذلك Mac و Linux و Windows) وسيسمح لك بالتصحيح بشكل متسق عبر الأجهزة وأنظمة التشغيل.

معلومة مفيدة: تأكد من تعطيل Windows Defender على جهازك. ستقوم هذه الخدمة الخارجية بفحص كل ملف مقروء، وقد تم الإبلاغ عن أنها تزيد بشكل كبير من وقت التحديث السريع مع next dev. هذه مشكلة معروفة، لا تتعلق بـ Next.js، لكنها تؤثر على تطوير Next.js.

مزيد من المعلومات

لمعرفة المزيد حول كيفية استخدام مصحح JavaScript، راجع التوثيق التالي:

خادم مخصص

بدء تطبيق Next.js برمجيًا باستخدام خادم مخصص.

وضع المسودة

يوفر Next.js ميزة وضع المسودة للتبديل بين الصفحات الثابتة والديناميكية. يمكنك تعلم كيفية عملها مع موجه الصفحات (Pages Router).