النشر يفشل، أو صفحة التطوير تطلع خطأ، والرسالة شكلها:
Module not found: Can't resolve './components/Header'
هذي صيغة Next.js و webpack. في مشاريع Vite، وهي أغلب مشاريع Lovable و Bolt، تطلع بشكل ثاني: Failed to resolve import "./components/Header" from "src/App.tsx". Does the file exist?، أو وقت البناء Rolldown failed to resolve import في Vite 8، و Rollup failed to resolve import في النسخ الأقدم. المعنى واحد: الكود يطلب ملف أو مكتبة، وأداة البناء ما لقتها في المكان المكتوب.
اقرأ الرسالة: الجواب فيها
الرسالة تقول لك شيئين: إيش اللي ما انلقى (المسار بين علامتي التنصيص)، ومين طلبه (الملف اللي فيه سطر الاستيراد). قبل أي شي، شوف المسار:
- إذا يبدأ بـ
./أو../: ملف من ملفات منتجك. - إذا يبدأ بـ
@/أو~/: اختصار لمجلد في منتجك (alias). - إذا اسم بدون نقطة، مثل
axiosأوdate-fns: مكتبة خارجية.
كل نوع له سبب مختلف.
1. حرف كبير وحرف صغير
هذا أشهر سبب، وأكثرها إزعاجًا. الكود يقول ./components/Header، والملف اسمه header.tsx. ويندوز وماك يعتبرونها نفس الملف، فيشتغل عندك. سيرفر البناء على Linux يعتبرها ملفين، فيفشل.
والأسوأ: لما تغيّر اسم الملف من header إلى Header على جهازك، Git على ويندوز وماك غالبًا ما يسجّل التغيير، لأنه يتجاهل فرق الحروف افتراضيًا. فتصلّح الاسم، وترفع، والخطأ يبقى.
كيف تتأكد: افتح مستودعك على موقع GitHub نفسه، مو على جهازك، وروح للمجلد، وشوف اسم الملف كما هو مكتوب هناك. GitHub يعرض لك نفس اللي يشوفه سيرفر البناء.
الحل الصح: تغيّر الاسم عن طريق Git نفسه: git mv header.tsx Header.tsx، وبعدها ترفع التعديل. وإذا اللي تغيّر اسمه مجلد، سوّها على خطوتين: git mv components temp ثم git mv temp Components.
2. الملف عندك، ومو في المستودع
الملف انكتب على جهازك أو داخل أداة الذكاء الاصطناعي، لكنه ما انرفع لـ GitHub. ممكن لأنه مذكور في .gitignore، أو لأن الأداة ما سجّلته في آخر مزامنة. نفس طريقة التأكد: دوّر عليه في GitHub. إذا مو موجود، هذا السبب.
3. مكتبة ناقصة من package.json
إذا المسار اسم مكتبة، افتح package.json ودوّر عليها تحت dependencies. إذا مو موجودة، معناها إنها مثبّتة على جهازك لكنها مو مسجّلة، أو إن الذكاء الاصطناعي كتب استيراد لمكتبة ما ثبّتها أصلًا. الحل تثبيتها بالطريقة الصحيحة (npm install ثم اسم المكتبة) عشان تنضاف للملف، ثم ترفع package.json و package-lock.json مع بعض.
وانتبه لحالة خاصة: Can't resolve 'fs' أو 'path' أو 'crypto'. هذي مكتبات موجودة في Node.js فقط، ومعناها إن كود مكتوب للسيرفر انحط في الواجهة. التثبيت هنا ما يحل شي: الكود نفسه في المكان الغلط، وأحيانًا يكون معه مفاتيح ما يفترض توصل للمتصفح أبد.
4. الاختصار @/ مو معرّف
منتجات كثيرة تكتب @/components/Header بدل مسار طويل. هذا الاختصار لازم يكون معرّف في مكانين: tsconfig.json عشان المحرر يفهمه، وإعدادات أداة البناء مثل vite.config.ts عشان البناء يفهمه. لما الذكاء الاصطناعي يضيفه في مكان وينساه في الثاني، المحرر ما يشتكي، والبناء يفشل.
قبل ما ترفع التعديل
بعد أي إصلاح من هذي، لا تعتمد على إن «المعاينة اشتغلت». شغّل على جهازك npm ci ثم npm run build، وهذا أقرب شي لسيرفر البناء: يثبّت المكتبات من الصفر حسب package-lock.json ويبني مثل ما يبني. لكنه يبني من الملفات اللي على جهازك، مو اللي في GitHub، فملف ما انرفع ما يكشفه هالفحص: شغّل git status قبل، وتأكد إن ما فيه ملف ناقص. إذا نجح، ارفع. وإذا فشل، صار عندك الخطأ الحقيقي بدون ما تنتظر النشر. لكن تذكّر إن فحص الحروف الكبيرة والصغيرة ما يطلع على ويندوز وماك، فهذا تتأكد منه من GitHub.
الحل اللي لا تقبله
لما تعطي أداة الذكاء الاصطناعي هذا الخطأ، أحيانًا تحذف سطر الاستيراد، أو تنشئ ملف فاضي بنفس الاسم عشان البناء ينجح. البناء فعلًا ينجح، لكن الجزء اللي كان يستخدم الملف صار ناقص أو فاضي، وتكتشف هذا من عميل. اسأل دائمًا «وين الملف الأصلي؟» قبل «كيف أخلّي البناء يمشي؟».
تحتاج يد؟
إذا المشكلة واحدة وواضحة، مكالمة استشارية تكفي: نلقى السبب ونصلّحه معك على المكالمة. وإذا البناء يفشل كل مرة بسبب جديد، هذي علامة إن منتجك يحتاج نظرة شاملة قبل الإطلاق في تدقيق جاهزية الإطلاق. وإذا تشتغل بـ Cursor أو Claude Code على جهازك، شوف مشاكل Cursor الأشهر.