تصحيح أخطاء 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 والإصدارات الأقدم، يؤدي هذا إلى تنشيط واجهة برمجة تطبيقات مصحح الأخطاء القديمة. في Node.js 8 والإصدارات الأحدث، سيؤدي ذلك إلى تنشيط واجهة برمجة تطبيقات المدقق.
الآثار الأمنية
نظرًا لأن مصحح الأخطاء لديه حق الوصول الكامل إلى بيئة تنفيذ 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 من أن رؤوس 'Host' للاتصال تحدد إما عنوان IP أو localhost بدقة.
تحظر سياسات الأمان هذه الاتصال بخادم تصحيح أخطاء عن بُعد عن طريق تحديد اسم المضيف. يمكنك تجاوز هذا القيد عن طريق تحديد إما عنوان IP أو عن طريق استخدام أنفاق ssh كما هو موضح أدناه.
عملاء الفحص
يتوفر مصحح أخطاء CLI بسيط مع node inspect myscript.js. يمكن للعديد من الأدوات التجارية ومفتوحة المصدر أيضًا الاتصال بـ Node.js Inspector.
Chrome DevTools 55+ ، Microsoft Edge
- الخيار 1: افتح
chrome://inspectفي متصفح يعتمد على Chromium أوedge://inspectفي Edge. انقر فوق الزر Configure وتأكد من إدراج المضيف والمنفذ المستهدفين. - الخيار 2: انسخ
devtoolsFrontendUrlمن إخراج/json/list(انظر أعلاه) أو نص تلميح--inspectوالصقه في Chrome.
راجع https://github.com/ChromeDevTools/devtools-frontend ، https://www.microsoftedgeinsider.com لمزيد من المعلومات.
Visual Studio Code 1.10+
- في لوحة Debug ، انقر فوق رمز الإعدادات لفتح
.vscode/launch.json. حدد "Node.js" للإعداد الأولي.
راجع https://github.com/microsoft/vscode لمزيد من المعلومات.
JetBrains WebStorm و IDEs JetBrains الأخرى
- قم بإنشاء تكوين تصحيح أخطاء Node.js جديد واضغط على Debug. سيتم استخدام
--inspectافتراضيًا لـ Node.js 7+. لتعطيل إلغاء تحديدjs.debugger.node.use.inspectفي IDE Registry. لمعرفة المزيد حول تشغيل وتصحيح أخطاء Node.js في WebStorm و IDEs JetBrains الأخرى ، تحقق من WebStorm online help.
chrome-remote-interface
- مكتبة لتسهيل الاتصالات بنقاط نهاية بروتوكول الفاحص. راجع https://github.com/cyrus-and/chrome-remote-interface لمزيد من المعلومات.
Gitpod
- ابدأ تكوين تصحيح أخطاء Node.js من عرض
Debugأو اضغط علىF5. تعليمات مفصلة
راجع https://www.gitpod.io لمزيد من المعلومات.
Eclipse IDE مع ملحق Eclipse Wild Web Developer
- من ملف
.js، اخترDebug As... > Node program، أو أنشئ تكوين تصحيح أخطاء لإرفاق مصحح الأخطاء بتطبيق Node.js قيد التشغيل (بدأ بالفعل بـ--inspect).
راجع https://eclipse.org/eclipseide لمزيد من المعلومات.
خيارات سطر الأوامر
يسرد الجدول التالي تأثير العلامات المختلفة لوقت التشغيل على تصحيح الأخطاء:
| العلم | المعنى |
|---|---|
--inspect | تمكين تصحيح الأخطاء باستخدام Node.js Inspector. استمع على العنوان والمنفذ الافتراضيين (127.0.0.1:9229) |
--inspect-brk | تمكين تصحيح الأخطاء باستخدام Node.js Inspector. استمع على العنوان والمنفذ الافتراضيين (127.0.0.1:9229)؛ توقف قبل بدء تشغيل كود المستخدم |
--inspect=[host:port] | تمكين وكيل الفاحص؛ اربط بالعنوان أو اسم المضيف (الافتراضي: 127.0.0.1)؛ استمع على المنفذ port (الافتراضي: 9229) |
--inspect-brk=[host:port] | تمكين وكيل الفاحص؛ اربط بالعنوان أو اسم المضيف (الافتراضي: 127.0.0.1)؛ استمع على المنفذ port (الافتراضي: 9229)؛ توقف قبل بدء تشغيل كود المستخدم |
--inspect-wait | تمكين وكيل الفاحص؛ استمع على العنوان والمنفذ الافتراضيين (127.0.0.1:9229)؛ انتظر حتى يتم إرفاق مصحح الأخطاء. |
--inspect-wait=[host:port] | تمكين وكيل الفاحص؛ اربط بالعنوان أو اسم المضيف (الافتراضي: 127.0.0.1)؛ استمع على المنفذ port (الافتراضي: 9229)؛ انتظر حتى يتم إرفاق مصحح الأخطاء. |
node inspect script.js | قم بإنشاء عملية فرعية لتشغيل نص المستخدم بعلامة --inspect ؛ واستخدم العملية الرئيسية لتشغيل مصحح أخطاء CLI. |
node inspect --port=xxxx script.js | قم بإنشاء عملية فرعية لتشغيل نص المستخدم بعلامة --inspect ؛ واستخدم العملية الرئيسية لتشغيل مصحح أخطاء CLI. استمع على المنفذ port (الافتراضي: 9229) |
تمكين سيناريوهات التصحيح عن بعد
نوصي بعدم جعل المصحح يستمع على عنوان IP عام أبدًا. إذا كنت بحاجة إلى السماح باتصالات التصحيح عن بعد، فنحن نوصي باستخدام أنفاق ssh بدلاً من ذلك. نحن نقدم المثال التالي لأغراض توضيحية فقط. يرجى فهم المخاطر الأمنية للسماح بالوصول عن بعد إلى خدمة مميزة قبل المتابعة.
لنفترض أنك تقوم بتشغيل Node.js على جهاز بعيد، remote.example.com، وتريد أن تكون قادرًا على تصحيح الأخطاء. على هذا الجهاز، يجب أن تبدأ عملية node مع استماع المفتش إلى المضيف المحلي فقط (الافتراضي).
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
تصحيح أخطاء تطبيق Node.js الخاص بك باستخدام أدوات مطوري Chrome من خلال استخدام عملية وسيطة تترجم بروتوكول Inspector المستخدم في Chromium إلى بروتوكول V8 Debugger المستخدم في Node.js. راجع https://github.com/node-inspector/node-inspector لمزيد من المعلومات.