تصحيح الأخطاء

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

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

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

قم بإنشاء ملف باسم .vscode/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: تصحيح المكدس بالكامل",
      "type": "node-terminal",
      "request": "launch",
      "command": "npm run dev",
      "serverReadyAction": {
        "pattern": "- Local:.+(https?://.+)",
        "uriFormat": "%s",
        "action": "debugWithChrome"
      }
    }
  ]
}

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

إذا كنت تغير رقم المنفذ الذي يبدأ منه التطبيق، فاستبدل 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، وتطبيق العميل/المتصفح.

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

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

ابدأ خادم التطوير كالمعتاد بتشغيل next dev، أو npm run dev، أو yarn dev. بمجرد بدء الخادم، افتح http://localhost:3000 (أو عنوان URL البديل) في Chrome. بعد ذلك، افتح أدوات المطور في Chrome (Ctrl+Shift+J على Windows/Linux، ⌥+⌘+I على macOS)، ثم انتقل إلى علامة التبويب Sources.

الآن، في أي وقت يصل كود جانب العميل إلى عبارة debugger، سيتم إيقاف تنفيذ الكود وسيظهر هذا الملف في منطقة التصحيح. يمكنك أيضًا الضغط على Ctrl+P على Windows/Linux أو ⌘+P على macOS للبحث عن ملف وتعيين نقاط التوقف يدويًا. لاحظ أنه عند البحث هنا، سيكون لملفات المصدر مسارات تبدأ بـ webpack://_N_E/./.

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

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

NODE_OPTIONS='--inspect' next dev

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

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

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

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

كن على علم أن تشغيل NODE_OPTIONS='--inspect' npm run dev أو NODE_OPTIONS='--inspect' yarn dev لن يعمل. سيحاول هذا بدء عدة مصححات أخطاء على نفس المنفذ: واحد لعملية npm/yarn وواحد لـ Next.js. ستحصل بعد ذلك على خطأ مثل Starting inspector on 127.0.0.1:9229 failed: address already in use في وحدة التحكم.

بمجرد بدء الخادم، افتح علامة تبويب جديدة في Chrome وقم بزيارة chrome://inspect، حيث يجب أن ترى تطبيق Next.js الخاص بك ضمن قسم Remote Target. انقر على inspect تحت تطبيقك لفتح نافذة منفصلة لأدوات المطور، ثم انتقل إلى علامة التبويب Sources.

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

التصحيح على Windows

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

{
  "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، راجع التوثيق التالي:

• تصحيح Node.js في VS Code: نقاط التوقف
• أدوات مطوري Chrome: تصحيح JavaScript