تنقيح تطبيقات 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 في لوحة الأوامر كي تبدأ جلسة التنقيح.

استعمال المنقح Debugger باستخدام Jetbrains WebStorm

انقر على القائمة التي تعرض ضبط المُشغل الآني runtime ثم اضغط على Edit Configurations ثم أنشئ ضبط لمنقح جافاسكربت Javascript Debug مع الرابط http://localhost:3000 ثم خصص ما تراه مناسبًا من متصفح وما يتعلق بالمشروع واضغط على OK.

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

التنقيح باستخدام أدوات مطوري الويب DevTools لمتصفح 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 بغض النظر عن المنصة التي تطور عليها تطبيقك (ويندوز أو لينكس أو ماك)، ويتيح لك تنقيح الشيفرة باستمرار عبر الأجهزة المختلفة وأنظمة التشغيل.

للمزيد من التفاصيل، انظر صفحة توثيق Node.js debugging in VS Code وصفحة Chrome DevTools الرسمية.

المصادر

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