تصحيح أخطاء Node.js
سيساعدك هذا الدليل على البدء في تصحيح أخطاء تطبيقات ونُسخ Node.js الخاصة بك.
تمكين مُفتّش الأخطاء
عند بدء التشغيل باستخدام مفتاح --inspect، يستمع مُعالِج Node.js إلى عميل تصحيح الأخطاء. بشكل افتراضي، سيستمع عند المضيف والمنفذ 127.0.0.1:9229. كما يتم تعيين معرف فريد (UUID) لكل عملية.
يجب أن يعرف عملاء مُفتّش الأخطاء ويحددون عنوان المضيف، والمنفذ، و معرف فريد (UUID) للاتصال. سيبدو عنوان URL الكامل مشابهًا لما يلي: ws://127.0.0.1:9229/0f2c936f-b1cd-4ac9-aab3-f63b0f33d55e.
سيبدأ Node.js أيضًا في الاستماع إلى رسائل تصحيح الأخطاء إذا تلقى إشارة SIGUSR1. (إشارة SIGUSR1 غير متوفرة على Windows.) في Node.js 7 والإصدارات الأقدم، يُنشّط هذا واجهة برمجة التطبيقات Debugger القديمة. في Node.js 8 والإصدارات الأحدث، سيتم تنشيط واجهة برمجة التطبيقات Inspector.
آثار أمنية
بما أن مُصحح الأخطاء لديه حق الوصول الكامل إلى بيئة تنفيذ Node.js، فقد يكون المهاجم الخبيث القادر على الاتصال بهذا المنفذ قادرًا على تنفيذ تعليمات برمجية عشوائية نيابة عن عملية Node.js. من المهم فهم الآثار الأمنية لكشف منفذ مُصحح الأخطاء على الشبكات العامة والخاصة.
كشف منفذ التصحيح علنًا أمر غير آمن
إذا تم ربط مُصحح الأخطاء بعنوان IP عام، أو بـ 0.0.0.0، فستتمكن أي عملاء يمكنهم الوصول إلى عنوان IP الخاص بك من الاتصال بمُصحح الأخطاء دون أي قيود وسيتمكنون من تشغيل تعليمات برمجية عشوائية.
بشكل افتراضي، يرتبط node --inspect بـ 127.0.0.1. تحتاج صراحةً إلى توفير عنوان IP عام أو 0.0.0.0، إلخ، إذا كنت تنوي السماح للاتصالات الخارجية بمُصحح الأخطاء. قد يعرضك القيام بذلك لتهديد أمني كبير محتمل. نقترح عليك ضمان وجود جدار حماية مناسب وضوابط وصول لمنع التعرض الأمني.
راجع قسم "تمكين سيناريوهات تصحيح الأخطاء عن بُعد" للحصول على بعض النصائح حول كيفية السماح بأمان لعملاء مُصحح الأخطاء عن بُعد بالاتصال.
التطبيقات المحلية لديها حق الوصول الكامل إلى مُفتّش الأخطاء
حتى إذا قمت بربط منفذ مُفتّش الأخطاء بـ 127.0.0.1 (الافتراضي)، فستتمتع جميع التطبيقات التي تعمل محليًا على جهازك بإمكانية وصول غير مقيّد. هذا حسب التصميم للسماح لمُصححات الأخطاء المحلية بالربط بسهولة.
المتصفحات وWebSockets وسياسة المصدر نفسه
يمكن لمواقع الويب المفتوحة في متصفح ويب إجراء طلبات WebSocket و HTTP بموجب نموذج أمان المتصفح. من الضروري وجود اتصال HTTP أولي للحصول على معرف جلسة مصحح الأخطاء فريد. تمنع سياسة المصدر نفسه مواقع الويب من إجراء اتصال HTTP هذا. لمزيد من الأمان ضد هجمات إعادة ربط DNS، يتحقق Node.js من أن رؤوس "المضيف" للاتصال تحدد عنوان IP أو localhost بدقة.
تمنع سياسات الأمان هذه الاتصال بخادم تصحيح أخطاء عن بُعد عن طريق تحديد اسم المضيف. يمكنك تجاوز هذا التقييد عن طريق تحديد عنوان IP أو باستخدام أنفاق ssh كما هو موضح أدناه.
عملاء المُفتش
يوجد مُصحح أخطاء سطر الأوامر الحد الأدنى متوفر مع node inspect myscript.js. يمكن أيضًا لعدة أدوات تجارية ومفتوحة المصدر الاتصال بمُفتش Node.js.
Chrome DevTools 55+، Microsoft Edge
- الخيار 1: افتح
chrome://inspectفي متصفح قائم على Chromium أوedge://inspectفي Edge. انقر فوق الزر "تكوين" وتأكد من إدراج المضيف والمنفذ المستهدفين. - الخيار 2: انسخ
devtoolsFrontendUrlمن إخراج/json/list(انظر أعلاه) أو نص تلميح--inspectوالصقه في Chrome.
راجع https://github.com/ChromeDevTools/devtools-frontend، https://www.microsoftedgeinsider.com لمزيد من المعلومات.
Visual Studio Code 1.10+
- في لوحة التصحيح، انقر فوق أيقونة الإعدادات لفتح
.vscode/launch.json. حدد "Node.js" للإعداد الأولي.
راجع https://github.com/microsoft/vscode لمزيد من المعلومات.
JetBrains WebStorm وأدوات IDE الأخرى من JetBrains
- أنشئ تكوين تصحيح أخطاء Node.js جديد واضغط على تصحيح الأخطاء. سيتم استخدام
--inspectافتراضيًا لـ Node.js 7+. لإلغاء التحديد، قم بإلغاء تحديدjs.debugger.node.use.inspectفي سجل IDE. لمعرفة المزيد حول تشغيل Node.js و تصحيح أخطائه في WebStorm وأدوات IDE الأخرى من JetBrains، تحقق من مساعدة WebStorm عبر الإنترنت.
chrome-remote-interface
- مكتبة لتسهيل الاتصالات بنقاط نهاية بروتوكول المفتش. اطلع على https://github.com/cyrus-and/chrome-remote-interface لمزيد من المعلومات.
Gitpod
- ابدأ تكوين تصحيح أخطاء Node.js من طريقة العرض "تصحيح الأخطاء" أو اضغط على
F5. تعليمات مفصلة
اطلع على https://www.gitpod.io لمزيد من المعلومات.
بيئة تطوير Eclipse المتكاملة مع ملحق Eclipse Wild Web Developer
- من ملف
.js، اخترDebug As... > Node program، أو أنشئ تكوين تصحيح أخطاء لإرفاق مصحح الأخطاء بتطبيق Node.js قيد التشغيل (بدأ بالفعل باستخدام--inspect).
اطلع على https://eclipse.org/eclipseide لمزيد من المعلومات.
خيارات سطر الأوامر
يسرد الجدول التالي تأثير علامات وقت التشغيل المختلفة على تصحيح الأخطاء:
| العلم | المعنى |
|---|---|
--inspect | تمكين تصحيح الأخطاء باستخدام مُفتش Node.js. الاستماع على العنوان والمنفذ الافتراضيين (127.0.0.1:9229) |
--inspect-brk | تمكين تصحيح الأخطاء باستخدام مُفتش Node.js. الاستماع على العنوان والمنفذ الافتراضيين (127.0.0.1:9229)؛ التوقف قبل بدء كود المستخدم |
--inspect=[host:port] | تمكين وكيل المفتش؛ الارتباط بالعنوان أو اسم المضيف host (الافتراضي: 127.0.0.1)؛ الاستماع على المنفذ port (الافتراضي: 9229) |
--inspect-brk=[host:port] | تمكين وكيل المفتش؛ الارتباط بالعنوان أو اسم المضيف host (الافتراضي: 127.0.0.1)؛ الاستماع على المنفذ port (الافتراضي: 9229)؛ التوقف قبل بدء كود المستخدم |
--inspect-wait | تمكين وكيل المفتش؛ الاستماع على العنوان والمنفذ الافتراضيين (127.0.0.1:9229)؛ الانتظار حتى يتم إرفاق مصحح الأخطاء. |
--inspect-wait=[host:port] | تمكين وكيل المفتش؛ الارتباط بالعنوان أو اسم المضيف host (الافتراضي: 127.0.0.1)؛ الاستماع على المنفذ port (الافتراضي: 9229)؛ الانتظار حتى يتم إرفاق مصحح الأخطاء. |
node inspect script.js | إنشاء عملية فرعية لتشغيل برنامج نصوص المستخدم ضمن علامة --inspect؛ واستخدام العملية الرئيسية لتشغيل مصحح أخطاء سطر الأوامر. |
node inspect --port=xxxx script.js | إنشاء عملية فرعية لتشغيل برنامج نصوص المستخدم ضمن علامة --inspect؛ واستخدام العملية الرئيسية لتشغيل مصحح أخطاء سطر الأوامر. الاستماع على المنفذ port (الافتراضي: 9229) |
تمكين سيناريوهات تصحيح الأخطاء عن بُعد
نوصي بعدم السماح أبدًا لبرنامج تصحيح الأخطاء بالاستماع على عنوان IP عام. إذا كنت تحتاج إلى السماح باتصالات تصحيح أخطاء عن بُعد، فنحن نوصي باستخدام أنفاق SSH بدلاً من ذلك. نحن نقدم المثال التالي لأغراض توضيحية فقط. يُرجى فهم المخاطر الأمنية المترتبة على السماح بالوصول عن بُعد إلى خدمة مُميزة قبل المتابعة.
لنفترض أنك تقوم بتشغيل Node.js على جهاز بعيد، remote.example.com، ترغب في تصحيح أخطائه. على هذا الجهاز، يجب عليك بدء عملية node مع الاستماع لمُفتش localhost فقط (الافتراضي).
node --inspect app.jsالآن، على جهازك المحلي الذي ترغب في بدء اتصال عميل تصحيح الأخطاء منه، يمكنك إعداد نفق SSH:
ssh -L 9225:localhost:9229 remote.example.comيبدأ هذا جلسة نفق SSH حيث سيتم توجيه اتصال إلى المنفذ 9221 على جهازك المحلي إلى المنفذ 9229 على remote.example.com. يمكنك الآن إرفاق مُصحح أخطاء مثل Chrome DevTools أو Visual Studio Code إلى localhost:9221، والذي يجب أن يكون قادرًا على تصحيح الأخطاء كما لو أن تطبيق Node.js قيد التشغيل محليًا.
مُصحح الأخطاء القديم
تم إهمال مُصحح الأخطاء القديم اعتبارًا من Node.js 7.7.0. يُرجى استخدام --inspect و Inspector بدلاً من ذلك.
عند بدء التشغيل باستخدام مفاتيح --debug أو --debug-brk في الإصدار 7 وما قبله، يستمع Node.js إلى أوامر تصحيح الأخطاء التي يحددها بروتوكول تصحيح أخطاء V8 المُلغى على منفذ TCP، افتراضيًا 5858. يمكن لأي عميل مُصحح أخطاء يتحدث هذا البروتوكول الاتصال بعملية التشغيل وتصحيح أخطائها؛ وهناك بعض العملاء الشائعين المدرجين أدناه.
لم يعد بروتوكول تصحيح أخطاء V8 مُحافظًا عليه أو موثقًا.
مُصحح الأخطاء المدمج
ابدأ node debug script_name.js لبدء البرنامج النصي الخاص بك ضمن مُصحح الأخطاء سطر الأوامر المدمج. يبدأ البرنامج النصي الخاص بك في عملية Node.js أخرى بدأت بخيار --debug-brk، وتقوم عملية Node.js الأولية بتشغيل البرنامج النصي _debugger.js والاتصال بالهدف الخاص بك. راجع الوثائق لمزيد من المعلومات.
node-inspector
استخدم Chrome DevTools في تصحيح أخطاء تطبيق Node.js الخاص بك باستخدام عملية وسيطة تُترجم بروتوكول المفتش المستخدم في Chromium إلى بروتوكول مُصحح أخطاء V8 المستخدم في Node.js. اطلع على https://github.com/node-inspector/node-inspector لمزيد من المعلومات.