حل ModuleNotFoundError واختلاف المفسر

افهم الأسباب المحتملة

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

1. حدد مفسر التنفيذ

شغل تشخيصا صغيرا في سياق الفشل نفسه: مفسر المحرر أو نواة الدفتر أو أمر الطرفية. سجل sys.executable والإصدار الرئيسي والفرعي وsys.prefix وsys.base_prefix. يشير اختلاف البادئتين في venv العادية إلى عمل العملية داخل البيئة. قارن السياقين الناجح والفاشل. لا تفترض أن تنشيط طرفية يغير محررا أو نواة يعملان بالفعل.

import sys

print(sys.executable)
print(sys.version_info[:2])
print(sys.prefix)
print(sys.base_prefix)

2. ميز الاسم والحجب والاعتماد الداخلي

اقرأ الاسم المفقود الأخير وقارنه بتوثيق تثبيت الاعتمادية. تحقق من اسم الاستيراد الصحيح قبل التفكير في التثبيت. تستطيع importlib.util.find_spec فحص العثور على اسم علوي معروف؛ استخدم اسما حرفيا معروفا لأن فحص الأسماء المنقوطة قد يستورد الأصل. راجع ملفات مثل json.py أو typing.py وافحص مصدر الوحدات التي تحمل. أعد تسمية التعارض ثم أعد تشغيل العملية.

import importlib.util

spec = importlib.util.find_spec("json")
print(spec is not None)

True

3. وحد بيئة المشروع

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

python -m pip --version

4. تحقق من الإصلاح في السياق الأصلي

أعد الاستيراد المصغر بزر التشغيل أو الأمر الذي فشل أصلا، وتحقق من اتفاق حقائق المفسر مع البيئة المختارة. إذا نجحت الحزمة العليا وفشل اعتماد داخلي، افحص التتبع الجديد ولا تعلن النجاح. للاستيرادات النسبية استخدم نقطة الدخول الموثقة، وغالبا python -m package.module، من المكان المقصود. نجاح طرفية أخرى دليل للمقارنة لكنه لا يثبت استعمال التطبيق الأصلي للبيئة المصححة.

امنع تكرار المشكلة

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