إذا تحولت نقطة التوقف إلى دائرة رمادية مفرغة في VS Code على جهاز Mac الخاص بك، فهذا يعني أن مصحح الأخطاء لم يتمكن من تسجيلها. ابدأ بالتحقق مما إذا كان السطر قابلاً للتنفيذ وما إذا كان مصحح الأخطاء النشط يدعم ذلك الملف. بعد ذلك، تأكد من أن جلسة تصحيح الأخطاء تقوم بتشغيل الكود الذي تقوم بتحريره. لا يحدد المؤشر بمفرده السبب المنطبق؛ ويساعد هذا التسلسل في تضييق الاحتمالات دون اللجوء إلى التخمين لإيجاد حل شامل. يصف دليل تصحيح الأخطاء في VS Code الدائرة المفرغة وأسبابها الشائعة.

تأكد من حالة نقطة التوقف التي تراها

الدائرة الحمراء المصمتة تعني نقطة توقف مُمكّنة؛ والدائرة الرمادية المصمتة تعني أنها معطلة. أما الدائرة الرمادية المفرغة فتعني أن مصحح الأخطاء لم يتمكن من تسجيل نقطة التوقف. تذكر وثائق VS Code سببين شائعين: السطر لا يحتوي على كود قابل للتنفيذ، أو أن مصحح الأخطاء لا يدعم ملف المصدر هذا. قد تظهر نقاط التوقف التي يتعذر تسجيلها مفرغة أيضًا عند بدء الجلسة؛ كما أن تعديلات المصدر أثناء الجلسة دون دعم التحرير المباشر (live-edit) يمكن أن تتسبب في ظهور المؤشر نفسه. قد يختلف السلوك الدقيق باختلاف اللغة وملحق مصحح الأخطاء.

على نظام macOS، افتح Run and Debug باستخدام Shift–Command–D. في قسم BREAKPOINTS الخاص به، حدد مكان الإدخال ذي الصلة وتأكد من تمكينه. تتيح لك طريقة العرض هذه إدارة نقاط التوقف، لكنها لا تشرح بمفردها سبب رفض مصحح الأخطاء لإحداها. احتفظ بالمحرر مفتوحًا عند السطر المحدد حتى تتمكن من مقارنة موقع المصدر بالملف الذي تستخدمه جلستك. VS Code: تصحيح الكود

تحقق مما إذا كان السطر قابلاً للتنفيذ

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

إذا كان الكود مُولَّدًا (generated)، أو مُترجمًا من لغة إلى أخرى (transpiled)، أو مُجمَّعًا (bundled)، أو يختلف بأي شكل آخر عن الملف الذي ينفذه البرنامج قيد التشغيل، فقد يحتاج مصحح الأخطاء إلى خرائط المصدر (source maps) أو إعداد آخر خاص باللغة لربط موقع المحرر بالكود في وقت التشغيل (runtime). لا يحدد دليل VS Code العام تكوينًا شاملاً واحدًا لهذه الحالة. تحقق من وثائق ملحق مصحح الأخطاء وإعدادات البناء (build) التي تستخدمها قبل تغيير إعدادات الربط والتخطيط.

تحقق من مصحح الأخطاء النشط والجلسة

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

اضغط على F5 لبدء تصحيح الأخطاء، أو استخدم Run and Debug لتحديد تكوين معين. قد يعمل البرنامج البسيط انطلاقًا من الملف النشط، ولكن التطبيق الذي يحتوي على نقطة إدخال معينة، أو وسيطات (arguments)، أو متغيرات بيئية، أو هدف إرفاق (attach target) قد يحتاج إلى تكوين داخل ملف launch.json. بالنسبة لإعداد الإرفاق، تأكد من أن العملية المستهدفة قيد التشغيل بالفعل في وضع تصحيح الأخطاء ومن تطابق تفاصيل الاتصال. قد تظل نقطة التوقف الموضوعة بشكل صحيح في ملف مختلف عن المصدر المحمَّل للبرنامج غير مُتحقق منها. VS Code: تكوين تصحيح الأخطاء

تضييق نطاق السبب عبر تسلسل خطوات قصير

استخدم هذا الترتيب، مع تغيير شيء واحد في كل مرة لكي تكون النتيجة ذات مغزى:

  1. في BREAKPOINTS، تحقق من تمكين نقطة التوقف ولاحظ ملفها وسطرها.
  2. انقلها إلى عبارة برمجية قابلة للتنفيذ في ذلك الملف.
  3. ابدأ تكوين تصحيح الأخطاء المطلوب باستخدام F5 ولاحظ ما إذا كانت العلامة ستُسجَّل.
  4. إذا بقيت مفرغة، فتحقق من أن مصحح الأخطاء المحدد يدعم الملف وأن ملحقه مثبت ونشط.
  5. تأكد من أن التكوين يُشغِّل البرنامج المبني من المصدر الذي تعرضه أو يرتبط به. راجع نقطة الإدخال، ودليل العمل، وأي مهمة بناء أو مهمة سابقة للتشغيل (pre-launch task) ذات صلة بمشروعك.
  6. إذا كان التطبيق يقوم بتحويل المصدر (transform)، فراجع تعليمات مصحح أخطاء اللغة لتعيين ملفات المحرر إلى كود وقت التشغيل.

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

ما يمكن أن يخبرك به المؤشر وما لا يمكنه إخبارك به

تخبرك الدائرة المفرغة أن مصحح الأخطاء لم يسجل نقطة التوقف تلك. ولا يمكنها، بمفردها، التمييز بين سطر غير قابل للتنفيذ، أو مصدر غير مدعوم، أو عدم تطابق بين كود المحرر وكود وقت التشغيل، أو قيود أخرى خاصة بمصحح الأخطاء. الخطوة التالية الأكثر فائدة هي اختبار سطر قابل للتنفيذ بوضوح في الجلسة المقصودة، ثم التحقق من مصحح الأخطاء وتعيين المصدر إذا استمر فشل التسجيل. على نظام Mac، عناصر التحكم الأساسية هي نفسها: هامش محرر VS Code (gutter)، وعرض Run and Debug، والمفتاح F5، والاختصار Shift–Command–D؛ ويجب أن تأتي الإصلاحات الخاصة بمصحح الأخطاء من وثائق الملحق أو بيئة التشغيل.

المصادر