تنقيح تطبيقات Next.js

تشرح صفحة التوثيق هذه كيفية تنقيح شيفرة الواجهتين الأمامية والخلفية بدعم كامل لملفات الربط المصدرية source maps وذلك باستخدام منقح VS Code أو أدوات مطورري ويب المدمجة مع المتصفح Google Chrome.

بالإمكان أيضًا تنقيح تطبيقات Next.js باستخدام أي مُنقّح قادر على الارتباط بخادم Node.js، وللاطلاع على هذه المنقحات راجع دليل التنقيح في Node.js.

تنقيح تطبيقات Next.js باستخدام VS Code

أنشئ ملفًا بالاسم vscode/launch.json. في المجلد الجذري للمشروع يضم المحتوى التالي:

{
  "version": "0.2.0",
  "configurations": [
    {
      "name": "Next.js: debug server-side",
      "type": "node-terminal",
      "request": "launch",
      "command": "npm run dev"
    },
    {
      "name": "Next.js: debug client-side",
      "type": "pwa-chrome",
      "request": "launch",
      "url": "http://localhost:3000"
    },
    {
      "name": "Next.js: debug full stack",
      "type": "node-terminal",
      "request": "launch",
      "command": "npm run dev",
      "console": "integratedTerminal",
      "serverReadyAction": {
        "pattern": "started server on .+, url: (https?://.+)",
        "uriFormat": "%s",
        "action": "debugWithChrome"
      }
    }
  ]
}

يمكن استبدال الأمر npm run dev بالأمر yarn dev إن كنت تستخدم Yarn. إن غيّرت رقم المنفذ الذي يعمل عليه تطبيقك، ضع هذا الرقم مكان القيمة 3000 في العنوان http://localhost:3000.

انتقل الآن إلى لوحة التنقيح (Ctrl+Shift+D في ويندوز ولينكس و D+⌘+⇧ في ماك) ثم اختر إعدادات للتشغيل واضغط بعدها الزر F5 أو يمكنك النقر على الخيار Debug > Start Debugging في لوحة الأوامر كي تبدأ جلسة التنقيح.

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

يجري التنقيح في الواجه الأمامية و الخلفية لتطبيق Next.js، وسنناقش هذا تاليًا.

شيفرة الواجهة الأمامية

شغّل خادم التطوير كالعادة بتنفيذ الأمر next dev أو npm run dev أو yarn dev، وعندما يعمل الخادم افتح العنوان http://localhost:3000 في Chrome. انتقل بعد ذلك إلى أدوات مطوري ويب (Ctrl+Shift+J في ويندوز ولينكس أو I+⌘+⌥ في ماك)، وبعدها إلى النافذة الفرعية "Sources".

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

شيفرة الواجهة الخلفية

كي تنقح شيفرة الواجهة الخلفية، عليك أن تمرر الراية inspect-- إلى عملية Node.js التي تجري خلف الستار:

NODE_OPTIONS='--inspect' next dev

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

"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://inspect حيث سترى تطبيق Next.js ضمن قسم "هدف بعيد Remote Target". انقر على "تفحّص Inspect" تحت التطبيق لفتح نافذة أدوات تطوير ويب جديدة وانتقل بعدها إلى "مصادر Sources".

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

التنقيح في ويندوز

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

"dev": "cross-env NODE_OPTIONS='--inspect' next dev",

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

المصادر

الصفحة Debugging من توثيق Next.js الرسمي.

Next.js/debugging

تنقيح تطبيقات Next.js