دليل التصحيح

سيساعدك هذا الدليل للبدء في تصحيح سكريبتات و تطبيقات الـ Node.js الخاصة بك.

تمكين المدقق

عند بدء الـ Node.js مع تمكين --inspect، يتم الانصات إلى عملية تصحيح، و افتراضيا، يتم هذا الانصات عبر المضيف و المنفذ 127.0.0.1:9229. يتم إعطاء كل عملية إنصات رقم UUID حصري.

يجب على عميل التدقيق معرفة و تحديد عنوان المضيف و رقم المنفذ، إضافة إلى الـUUID حتى يتم الاتصال. سيبدو العنوان كاملا كما يلي: ws://127.0.0.1:9229/0f2c936f-b1cd-4ac9-aab3-f63b0f33d55e

ستستمع الـ Node.js إلى رسائل التصحيح إذا تلقت إشارة SIGUSR1 (SIGUSR1 غير متوفر على ويندوز)، حيث انه في الـ Node.js 7 و ما قبله، ينشط إستقبال هذه الإشارة واجهة برمجة التطبيقات القديمة الخاصة بالتصحيح، أما في الـ Node.js 8 و ما بعده، فذلك ينشط واجهة برمجة التطبيقات الخاصة بالمدقق

تأثيرات أمنية

بما أن لدى مصحح الأخطاء وصولاً كاملاً إلى بيئة تنفيذ الـ Node.js، قد يمكن لبرمجية ضارة متصلة بهذا المنفذ أن تنفذ شيفرات عشوائية من خلال عملية الـ Node، ولذلك فإنه من المهم فهم التأثيرات الأمنية المحتملة التي تنتج عن إتاحة المنفذ الخاص بمصحح الأخطاء في الشبكات العامة و الخاصة.

إتاحة المنفذ الخاص بالتصحيح للعامة غير آمن

إذا كان لمصحح الأخطاء عنوان عام، او كان عنوانه هو 0.0.0.0، فيمكن لأي عميل قادر على الوصول لعنوان الانترنت الخاص بك أن يتواصل مع مصحح الأخطاء بدون أية قيود، و سيتمكن من تنفيذ برمجيات عشوائية.

إفتراضيا، تأخذ العملية node --inspect العنوان 127.0.0.1، ويجب عليك تحديد العنوان العام لها صراحة سواء كان 0.0.0.0 أو غيره من العناوين إذا كنت تنوي ان تسمح بإتصالات خارجية لمصحح الأخطاء، ولكن فعل هذا قد يعرضك لمخاطر أمنية جمة. تأكد من توظيف الجدران النارية و صلاحيات الوصول المناسبة لمنع أي تهديد أمني.

إقرأ القسم المعنون بـ سيناريوهات تمكين تصحيح الأخطاء عن بعد للحصول على بعض النصائح حول كيفية تمكين الاتصالات عن بعد بمصحح الأخطاء بشكل آمن.

التطبيقات المحلية تمتلك الوصول الكامل للمدقق

حتى لو قمت بربط منقذ المدقق بالعنوان 127.0.0.1 (الإفتراضي)، فإن أي تطبيقات محلية ستحصل على صلاحية الوصول الكاملة له. لقد تم تصميم ذلك حتى يتسنى لمصححات الأخطاء المحلية أن ترتبط به بالشكل المناسب.

المتصفحات و مآخذ الويب و سياسة نفس الأصل

يمكن لمواقع الانترنت المفتوحة من متصفح أن تجري طلبات HTTP و webSockets تحت النموذج الأمني الخاص بالمتصفح، و يعد ضروريا إجراء اتصال HTTP مبدئي لأجل الحصول على معرف حصري خاص بجلسة تصحيح الأخطاء. تمنع سياسة نفس الأصل المواقع من إجراء هذا الإتصال وكتأمين من هجمات الـ DNS rebinding، يقوم الـ Node.js بالتحقق من أن الرؤوس الخاصة بالمضيف و الخاصة بالاتصال إما تحدد عنوانا أو localhost أو localhost6 بدقة.

تمنع سياسات التأمين هذه الإتصال عن طريق تحديد إسم المضيف بخادم لتصحيح الأخطاء عن بعد، لكن يمكنك إيجاد طريقة للالتفاف حول هذا بتحديد عنوان بروتوكول الانترنت أو باستعمال نفق ssh كما هو موصوف اسفله.

برامج التدقيق

هناك عدة أدوات مفتوحة المصدر يمكنها الإتصال بالدقق الخاص بالـ Node.js و ما يلي هي معلومات مبدئية عنها:

node-inspect

• مصحح أخطاء في سطر الأوامر مدعوم من مؤسسة الـ Node.js و يستعمل البروتوكول المسمى Inspector Protocol.
• تشحن نسخة منه مع الـ Node و يمكن استعماله بواسطة الأمر node inspect myscript.js.
• يمكن تثبيت آخر نسخة منه بشكل مستقل (npm install -g node-inspect على سبيل المثال) و يمكن استعمالها بواسطة الأمر node inspect myscript.js.

Chrome DevTools 55+

• الطريقة الأولى: قم بفتح العنوان chrome://inspect في أي متصفح مبني على Chromium. قم بالضغط على زر Configure و تأكد من أن المضيف و المنفذ في القائمة.
• الطريقة الثانية: قم بنسخ devtoolsFrontendUrl من الناتج عن /json/list (أنظر أعلاه) أو النص التلميحي الناتج عن --inspect و قم بلصقه في Chrome.

Visual Studio Code 1.10+

• في قائمة تصحيح الأخطاء، إضغط على ايقونة الإعدادات لفتح .vscode/launch.json. قم باختيار "Node.js" للتثبيت الأولي.

Visual Studio 2017+

• قم باختيار "Debug > Start Debugging" من القائمة أو قم بالضغط على F5.
• خطوات تفصيلية بالإنجليزية

JetBrains WebStorm 2017.1+ و منتجات JetBrains الأخرى

• قم بإنشاء إعدادات تصحيح جديدة خاصة بالـ Node.js و اضغط على Debug. سيتم استعمال --inspect افتراضياً بالنسبة للنسخ 7 فما فوق. لإلغاء ذلك، قم بإلغاء تمكين js.debugger.node.use.inspect في السجل الخاص بالبرنامج.

chrome-remote-interface

• مكتبة تسهل التواصل بأطراف اتصال بروتوكول التدقيق.

Gitpod

• قم بإنشاء إعدادات تصحيح الأخطاء الخاصة بالـ Node.js من Debug أو قم بالضغط على F5. هنا خطوات تفصيلية بالإنجليزية

Eclipse IDE مع إضافة إكليبس الشاملة لتطوير الويب

• من ملف .js، اختر "Debug As... > Node program", او
• إنشاء اعدادات المنقح لكي يتمكن من تشغيل تطبيق Node (بدأ بـ --inspect).

خيارات سطر الأوامر

يبين الجدول الآتي تأثير كل تخصيص خاص بوقت التشغيل على تصحيح الأخطاء:

سيناريوهات تمكين تصحيح الأخطاء عن بعد

نوصي دائما بعدم تشغيل مصحح الأخطاء على عنوان انترنت عام. إذا أردت تمكين تصحيح الأخطاء عن بعد، فننصح بإستعمال قنوات الـ ssh بدلا من ذلك. المثال الآتي لأغراض توضيحية فقط. يجب عليك فهم المخاطر الأمنية المحتملة عند السماح بالوصول عن بعد لخدمة ذات امتيازات قبل أن تمضي قدما.

فلنفترض أنك قمت بتشغيل الـ Node في حاسوب بعيد، remote.example.com على سبيل المثال، و تريد ان تتمكن من تصحيح الأخطاء فيها. في ذلك الحاسوب البعيد، عليك بدء عملية node مع جعل المدقق يستمع على المضيف المحلي فقط (وهو الافتراضي).

node --inspect server.js

الآن، و على حاسوبك المحلي الذي تريد من خلاله إنشاء اتصال بعميل تصحيح الأخطاء، يمكنك إنشاء قناة ssh:

ssh -L 9221:localhost:9229 user@remote.example.com

يقوم هذا الأمر بإنشاء جلسة لقناة ssh حيث يتم إعادة توجيه الإتصال من المنفذ 9221 على جهازك المحلي إلى المنفذ 9221 على النطاق remote.example.com. يمكنك الآن ربط مصحح أخطاء مثل Chrome DevTools أو Visual Studio Code بالعنوان localhost:9221 مما يعني أنه قادر على بدء تصحيح الأخطاء كما لو أن تطبيق الـ Node.js يشتغل محليا.

مصحح الأخطاء القديم

**لقد تم اعتبار مصحح الأخطاء القديم قديماً ابتداء من نسخة الـ Node 7.7.0. قم باستعمال --inspect أو المدقق بدلا منه.

عند تشغيل مصحح الأخطاء القديم مع --debug أو --debug-brk في النسخة 7 و ما قبلها، تستمع الـ Node.js إلى تعليمات التصحيح المعرفة من قبل بروتوكول التصحيح الخاص بالـ V8 الذي تم ايقاف تطويره و ذلك على منفذ TCP 5858 افتراضياً. يستطيع أي عميل تصحيح يستخدم هذا البروتوكول أن يتصل و يصحح العملية الجاري تنفيذها، و من أشهرها ما سيُذكر أسفله.

إن بروتوكول التصحيح الخاص بالـ V8 لم تعد يتم صيانته أو توثيقه دوريا.

مصحح الأخطاء المبني ضمنيا

قم بتنفيذ الأمر node debug script_name.js لبدء النص البرمجي الخاص بك عن طريق مصحح الأخطاء المبني ضمنيا في Node. يمكن للنص البرمجي الخاص بك أن يبدأ في عملية Node اخرى باستعمال --debug-brk كما تشغل عملية Node المبدئية الملف _debugger.js و توصلك بوجهتك.

node-inspector

قم بتصحيح الأخطاء في تطبيق Node.js الخاص بواسطة الـ Chrome DevTools و ذلك باستعمال عملية وسيطة تقوم بتحويل بروتوكول المدقق المستعمل في Chromium إلى بروتوكول تصحيح الأخطاء في الـ V8 المستعمل في الـ Node.js