حل خطأ ModuleNotFoundError و Cannot find module بالعربي

خطآن يواجههما كل مطوّر تقريبًا: ModuleNotFoundError في بايثون و Cannot find module في Node.js. كلاهما يقول الشيء نفسه: "طلبتَ كودًا من مكان ما، ولم أجده." لنفهم السبب ونحلّه بالترتيب.

الشكل الذي يظهر به الخطأ

في بايثون:

ModuleNotFoundError: No module named 'requests'

في Node.js:

Error: Cannot find module './utils'

الرسالة تخبرك دائمًا باسم الوحدة الناقصة بين علامتَي اقتباس — اقرأها أولًا، فهي نصف الحل.

الأسباب الخمسة الأكثر شيوعًا

الحل في بايثون خطوة بخطوة

1) ثبّت المكتبة بشكل صحيح

استخدم python -m pip لتضمن التثبيت في مفسّر بايثون نفسه الذي تشغّل به:

python -m pip install requests

2) تحقّق من البيئة الافتراضية (venv)

أكثر سبب خفيّ: ثبّتها عالميًّا لكنك تشغّل داخل بيئة افتراضية (أو العكس).

# فعّل البيئة أولًا
source venv/bin/activate      # على لينكس/ماك
venv\Scripts\activate         # على ويندوز
python -m pip install requests

3) انتبه لتسمية ملفّاتك

إذا سمّيت ملفّك random.py أو math.py، سيحاول بايثون استيراد ملفّك بدل المكتبة القياسية. أعد تسميته.

💡 نصيحة: import sys; print(sys.executable) يطبع مسار بايثون الذي يعمل فعلًا — قارنه بالمسار الذي ثبّتَ فيه المكتبة.

الحل في Node.js خطوة بخطوة

1) ثبّت الاعتماديات

بعد استنساخ أي مشروع، مجلّد node_modules لا يُرفع عادةً — أعِد بناءه:

npm install

2) فرّق بين وحدة مثبّتة وملفّ محلّي

import express from "express";   // مكتبة: من node_modules
import { sum } from "./utils.js"; // ملفّ محلّي: يبدأ بـ ./

نسيان ./ أمام الملفّات المحلّية سبب شائع جدًّا لـ Cannot find module.

3) تأكّد من الامتداد ونوع الوحدات

في وحدات ESM (عندما يكون "type": "module" في package.json) يجب أن تكتب الامتداد صراحةً:

import { sum } from "./utils.js"; // ✅ .js مطلوب في ESM

قائمة تحقّق سريعة

• هل شغّلت pip install / npm install؟
• هل أنت في البيئة/المجلّد الصحيح؟
• هل اسم الاستيراد مطابق تمامًا (حرف كبير/صغير)؟
• هل يبدأ المسار المحلّي بـ ./؟
• هل ملفّك يحمل اسم مكتبة بالخطأ؟

الخلاصة

ModuleNotFoundError و Cannot find module ليسا خطأً في منطق برنامجك، بل في مكان الكود: إمّا لم تُثبّت المكتبة، أو تشغّل من بيئة خاطئة، أو المسار غير صحيح. راجع القائمة أعلاه بالترتيب وستحلّه في دقائق.

تعمّق أكثر في إدارة الحزم في بايثون و الوحدات و npm في Node.js، أو راجع أخطاء بايثون الشائعة و أخطاء npm install.