الفرق بين المراجعتين لصفحة: «Next.js/debugging»

المراجعة الحالية بتاريخ 17:08، 3 يناير 2023

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

@@ سطر 1: / سطر 1: @@
 <noinclude>{{DISPLAYTITLE:تنقيح تطبيقات Next.js}}</noinclude>
-تشرح صفحة التوثيق هذه كيفية تنقيح شيفرة الواجهتين الأمامية والخلفية بدعم كامل لملفات الربط المصدرية source maps وذلك باستخدام [https://code.visualstudio.com/docs/editor/debugging منقح VS Code] أو [https://developers.google.com/web/tools/chrome-devtools أدوات مطورري ويب المدمجة مع المتصفح Google Chrome].
+تشرح صفحة التوثيق هذه كيفية تنقيح شيفرة الواجهتين الأمامية والخلفية بدعم كامل [[Next.js/source maps|لملفات الربط المصدرية]] source maps وذلك باستخدام [https://code.visualstudio.com/docs/editor/debugging منقح VS Code] أو [https://developers.google.com/web/tools/chrome-devtools أدوات مطورري ويب المدمجة مع المتصفح Google Chrome].
-بالإمكان أيضًا تنقيح تطبيقات Next.js باستخدام أي مُنقّح قادر على الارتباط بخادم Node.js، وللاطلاع على هذه المنقحات راجع دليل التنقيح في Node.js.
+بالإمكان أيضًا تنقيح تطبيقات Next.js باستخدام أي مُنقّح قادر على الارتباط ببيئة Node.js، وللاطلاع على هذه المنقحات راجع [https://nodejs.org/en/docs/guides/debugging-getting-started/ دليل التنقيح في Node.js].
 == تنقيح تطبيقات Next.js باستخدام VS Code ==
-أنشئ ملفًا بالاسم <code>vscode/launch.json.</code> في المجلد الجذري للمشروع يضم المحتوى التالي:<syntaxhighlight lang="json">
+أنشئ ملفًا بالاسم <code>vscode/launch.json.</code> في جذر مجلد المشروع يضم المحتوى التالي:<syntaxhighlight lang="json">
 {
    "version": "0.2.0",
@@ سطر 39: / سطر 39: @@
 انتقل الآن إلى لوحة التنقيح (Ctrl+Shift+D في ويندوز ولينكس و D+⌘+⇧ في ماك) ثم اختر إعدادات للتشغيل واضغط بعدها الزر F5 أو يمكنك النقر على الخيار Debug > Start Debugging في لوحة الأوامر كي تبدأ جلسة التنقيح.
-== التنقيح باستخدام أدوات مطوري ويب لمتصفح Chrome ==
+== استعمال المنقح Debugger باستخدام Jetbrains WebStorm ==
-يجري التنقيح في الواجه الأمامية و الخلفية لتطبيق Next.js، وسنناقش هذا تاليًا.
+انقر على القائمة التي تعرض ضبط المُشغل الآني runtime ثم اضغط على Edit Configurations ثم أنشئ ضبط لمنقح جافاسكربت Javascript Debug مع الرابط <nowiki>http://localhost:3000</nowiki> ثم خصص ما تراه مناسبًا من متصفح وما يتعلق بالمشروع واضغط على OK.
+شغل بعد ذلك هذا الضبط للمنقح وسيفتح المتصفح المختار تلقائيًا، وفي هذه اللحظة يجب أن تحصل على تطبيقين في وضع التنقيح، تطبيق Next.js مع بيئة node وتطبيق العميل الذي يعمل من طرف المتصفح.
+== التنقيح باستخدام أدوات مطوري الويب DevTools لمتصفح Chrome ==
+يجري التنقيح في الواجه الأمامية والخلفية لتطبيق Next.js، وسنناقش هذا تاليًا.
 === شيفرة الواجهة الأمامية ===
 شغّل خادم التطوير كالعادة بتنفيذ الأمر <code>next dev</code> أو <code>npm run dev</code> أو <code>yarn dev</code>، وعندما يعمل الخادم افتح العنوان <code><nowiki>http://localhost:3000</nowiki></code> في Chrome. انتقل بعد ذلك إلى أدوات مطوري ويب (Ctrl+Shift+J في ويندوز ولينكس أو I+⌘+⌥ في ماك)، وبعدها إلى النافذة الفرعية "Sources".
-في أي لحظة تصل فيها شيفرة الواجهة الأمامية إلى العبارة [[JavaScript/debugger|<code>debugger</code>]]، سيتوقف تنفيذ الشيفرة وسيظهر الملف في منطقة التنقيح. بغمكانك الضغط على المفتاحين Ctrl+P في ويندوز ولينكس أو  ⌘+P في ماك للبحث عن ملف ووضع نقاط التوقف breakpoint يدويًا. لاحظ أنه عند البحث هنا، ستبدأ مسارات الملفات بالعبارة <code>/./webpack://_N_E</code>.
+في أي لحظة تصل فيها شيفرة الواجهة الأمامية إلى العبارة [[JavaScript/debugger|<code>debugger</code>]]، سيتوقف تنفيذ الشيفرة وسيظهر الملف في منطقة التنقيح. بإمكانك الضغط على المفتاحين Ctrl+P في ويندوز ولينكس أو ⌘+P في ماك للبحث عن ملف ووضع نقاط التوقف breakpoint يدويًا. لاحظ أنه عند البحث هنا، ستبدأ مسارات الملفات بالعبارة <code>/./webpack://_N_E</code>.
 === شيفرة الواجهة الخلفية ===
-كي تنقح شيفرة الواجهة الخلفية، عليك أن تمرر الراية  [[Node.js/cli|<code>inspect--</code>]] إلى عملية Node.js التي تجري خلف الستار:<syntaxhighlight lang="bash">
+كي تنقح شيفرة الواجهة الخلفية، عليك أن تمرر الراية [[Node.js/cli|<code>inspect--</code>]] إلى عملية Node.js التي تجري خلف الستار:<syntaxhighlight lang="bash">
 NODE_OPTIONS='--inspect' next dev
-</syntaxhighlight>إن كنت تستخدم <code>npm run dev</code> أو <code>yarn dev</code> (راجع صفحة [[Next.js|البدء مع Next.js]]) فعليك تحديث السكربت <code>dev</code> في الملف  <code>package.json</code>:<syntaxhighlight lang="json">
+</syntaxhighlight>إن كنت تستخدم <code>npm run dev</code> أو <code>yarn dev</code> (راجع صفحة [[Next.js|البدء مع Next.js]]) فعليك تحديث السكربت <code>dev</code> في الملف <code>package.json</code>:<syntaxhighlight lang="json">
 "dev": "NODE_OPTIONS='--inspect' next dev"
-</syntaxhighlight>ستبدو الطرفية عند إقلاع خادم تطوير  Next.js بوجود الراية <code>inspect--</code> مشابهة للتالي:<syntaxhighlight lang="bash">
+</syntaxhighlight>ستبدو الطرفية عند إقلاع خادم تطوير Next.js بوجود الراية <code>inspect--</code> مشابهة للتالي:<syntaxhighlight lang="bash">
 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
-</syntaxhighlight>'''ملاحظة''': لن يعمل أي من الأمرين <code>NODE_OPTIONS='--inspect' npm run dev</code> أو <code>NODE_OPTIONS='--inspect' yarn dev</code>. إذ سيحاول هذان الأمران تشغيل عدة منقحات على المنفذ نفسه، الأول لتنفيذ عملية npm/yarn والأخرى لتنفيذ Next.js، وعندها سيظهر خطأ مثل <code>Starting inspector on 127.0.0.1:9229 failed: address already in use</code> على الطرفية.
+</syntaxhighlight>'''ملاحظة''': لن يعمل أي من الأمرين <code>NODE_OPTIONS='--inspect' npm run dev</code> أو <code>NODE_OPTIONS='--inspect' yarn dev</code>. إذ سيحاول هذان الأمران تشغيل عدة منقحات على المنفذ نفسه، الأول لتنفيذ عملية npm/yarn والآخر لتنفيذ Next.js، وعندها سيظهر خطأ مثل <code>Starting inspector on 127.0.0.1:9229 failed: address already in use</code> على الطرفية.
-بمجرد أن ينتهي تحميل المتصفح، افتح نافذة جديدة وانتقل إلى العنوان <code>chrome://inspect</code> حيث سترى تطبيق Next.js ضمن قسم "هدف بعيد Remote Target". انقر على "تفحّص Inspect" تحت التطبيق لفتح نافذة أدوات تطوير ويب جديدة وانتقل بعدها إلى "مصادر Sources".
+بمجرد أن ينتهي تحميل المتصفح، افتح نافذة جديدة وانتقل إلى العنوان <code>chrome://inspect</code> إذ سترى تطبيق Next.js ضمن قسم "هدف بعيد Remote Target". انقر على "تفحّص Inspect" تحت التطبيق لفتح نافذة أدوات تطوير ويب جديدة وانتقل بعدها إلى "مصادر Sources".
-يتشابه تنقيح شيفرة الواجهة الخلفية و الأمامية كثيرًا عند استخدام أدوات مطوري ويب، لكن عندما تبحث عن ملف بالضغط على المفاتيح Ctrl+P  أو  ⌘+P، ستبدأ مسارات الملفات المصدرية بالعبارة <code>/./webpack://{application-name}</code>، حيث تُستبدل العبارة <code>{application-name}</code> باسم التطبيق وفقًا للملف <code>package.json</code>.
+يتشابه تنقيح شيفرة الواجهة الخلفية والأمامية كثيرًا عند استخدام أدوات مطوري ويب، لكن عندما تبحث عن ملف بالضغط على المفاتيح Ctrl+P أو ⌘+P، ستبدأ مسارات الملفات المصدرية بالعبارة <code>/./webpack://{application-name}</code>، إذ تُستبدل العبارة <code>{application-name}</code> باسم التطبيق وفقًا للملف <code>package.json</code>.
 === التنقيح في ويندوز ===
-قد تعترض مستخدمي نظام التشغيل ويندوز بعض المشاكل عند استخدام متغير البيئة <code>NODE_OPTIONS='--inspect'</code> لأنها غير مدعومة على منصات ويندوز. وللالتفاف على الموضوع، ثبّت الحزمة <code>[https://www.npmjs.com/package/cross-env cross-env]</code> كاعتمادية تطوير (<code>dev--</code>  إن استخدمت npm أو <code>D-</code> إن استخدمت yarn) واستبدل سكربت  <code>dev</code> بالسكربت التالي: <syntaxhighlight lang="json">
+قد تعترض مستخدمي نظام التشغيل ويندوز بعض المشاكل عند استخدام متغير البيئة <code>'NODE_OPTIONS='--inspect</code> لأنها غير مدعومة على منصات ويندوز. وللالتفاف على الموضوع، ثبّت الحزمة <code>[https://www.npmjs.com/package/cross-env cross-env]</code> كاعتمادية تطوير (<code>dev--</code> إن استخدمت npm أو <code>D-</code> إن استخدمت yarn) واستبدل سكربت <code>dev</code> بالسكربت التالي: <syntaxhighlight lang="json">
 "dev": "cross-env NODE_OPTIONS='--inspect' next dev",
 </syntaxhighlight>سيضبط <code>cross-env</code> متغير البيئة <code>NODE_OPTIONS</code> بغض النظر عن المنصة التي تطور عليها تطبيقك (ويندوز أو لينكس أو ماك)، ويتيح لك تنقيح الشيفرة باستمرار عبر الأجهزة المختلفة وأنظمة التشغيل.
+للمزيد من التفاصيل، انظر صفحة توثيق [https://code.visualstudio.com/docs/nodejs/nodejs-debugging#_breakpoints Node.js debugging in VS Code] وصفحة [https://developer.chrome.com/docs/devtools/ Chrome DevTools] الرسمية.
+== اقرأ أيضًا ==
+* [https://academy.hsoub.com/programming/workflow/%D8%A3%D8%AF%D9%88%D8%A7%D8%AA-%D9%85%D8%B7%D9%88%D8%B1%D9%8A-%D8%A7%D9%84%D9%88%D9%8A%D8%A8-%D8%A7%D9%84%D9%85%D8%AF%D9%85%D8%AC%D8%A9-%D9%81%D9%8A-%D8%A7%D9%84%D9%85%D8%AA%D8%B5%D9%81%D8%AD%D8%A7%D8%AA-r1439/ أدوات مطوري ويب المدمجة مع المتصفحات]
+* [[Next.js/middleware|البرمجيات الوسطية في Next.js]]
+* [[Next.js/error handling|معالجة الأخطاء في Next.js]]
 == المصادر ==
+* الصفحة [https://nextjs.org/docs/advanced-features/debugging Debugging] من توثيق Next.js الرسمي.
-* الصفحة Debugging من توثيق Next.js الرسمي.
-== اقرأ أيضًا ==
-* [https://academy.hsoub.com/programming/workflow/%D8%A3%D8%AF%D9%88%D8%A7%D8%AA-%D9%85%D8%B7%D9%88%D8%B1%D9%8A-%D8%A7%D9%84%D9%88%D9%8A%D8%A8-%D8%A7%D9%84%D9%85%D8%AF%D9%85%D8%AC%D8%A9-%D9%81%D9%8A-%D8%A7%D9%84%D9%85%D8%AA%D8%B5%D9%81%D8%AD%D8%A7%D8%AA-r1439/ أدوات مطوري ويب المدمجة مع المتصفحات].
+[[تصنيف:Next.js|{{SUBPAGENAME}}]]
-* [[Next.js/middleware|الأدوات الوسطية في Next.js]].
+[[تصنيف:Next.js Advanced Features|{{SUBPAGENAME}}]]
-* [[Next.js/error handling|معالجة الأخطاء في Next.js]].