Command "npm run build" exited with 1: كيف تلقى السبب؟

ترفع منتجك، والنشر يفشل، وآخر سطر في سجل البناء:

Error: Command "npm run build" exited with 1

أول شي لازم تعرفه: هذا السطر ما يقول لك إيش الغلط. معناه فقط إن أمر البناء انتهى بفشل، والرقم 1 معناه «فشل» بشكل عام. السبب الحقيقي مكتوب فوقه، في مكان ما في السجل.

كيف تقرأ سجل البناء

1. افتح النشر الفاشل في لوحة الاستضافة، وافتح سجل البناء (Build Logs).
2. لا توقف عند آخر سطر. اطلع فوق سطر سطر حتى تلقى أول رسالة خطأ، غالبًا لونها أحمر، أو فيها كلمة error أو ERR!.
3. انسخ هالرسالة بالضبط، مع السطر اللي قبلها والسطر اللي بعدها. هي اللي تحتاجها، سواء بحثت عنها أو أرسلتها لمهندس.

الرسائل اللي بعد أول خطأ غالبًا نتيجة له، مو أخطاء مستقلة.

الأسباب الأشهر

1. أخطاء TypeScript

في مشاريع كثيرة، أمر البناء يفحص الأنواع قبل ما يبني، مثل tsc && vite build. المعاينة في Lovable أو Bolt ما تفحص الأنواع أصلًا وتعرض الصفحة، لكن البناء الحقيقي يفشل لو فيه خطأ واحد فقط. علامتها: رسائل فيها TS ورقم، مثل TS2322، مع اسم الملف ورقم السطر.

2. فحص الكود (Lint) في Next.js

في Next.js 15 وما قبله، next build يشغّل فحص ESLint، وبعض قواعده توقف البناء. من Next.js 16 البناء ما يشغّل الفحص أبد، فهذا السبب ما يطلع إلا في المشاريع الأقدم. ومشاريع Create React App القديمة تعامل التحذيرات كأخطاء لما تنبني على سيرفر، ورسالتها: Treating warnings as errors because process.env.CI = true.

3. مكتبة ناقصة من package.json

المكتبة موجودة على جهازك لأنك ثبّتها مرة بيدك، لكنها مو مكتوبة في package.json، فسيرفر البناء ما يثبّتها. علامتها: رسالة مثل Cannot find module أو Module not found، وشرحناها في درس Module not found.

4. اسم ملف بحرف كبير وصغير

يشتغل على ويندوز وماك، ويفشل على سيرفر البناء اللي يفرّق بين Header.tsx و header.tsx. نفس الدرس فوق يشرح كيف تصلحه صح، لأن تغيير الاسم العادي ما يكفي.

5. نسخة Node غير

جهازك عليه نسخة من Node.js، وسيرفر البناء عليه نسخة ثانية، وبعض المكتبات تحتاج نسخة أحدث. علامتها: رسالة فيها engine أو Unsupported، أو خطأ غريب داخل مكتبة ما لمستها. تقدر تحدد نسخة Node في إعدادات الاستضافة.

6. الذاكرة خلصت

المنتجات الكبيرة أحيانًا تحتاج ذاكرة وقت البناء أكثر من اللي يعطيها السيرفر، ورسالتها فيها JavaScript heap out of memory. هذا مو خطأ في منطق الكود، لكنه غالبًا علامة إن الملفات كبرت أكثر من اللازم، أو إن فيه مكتبة ضخمة انضافت وما أحد يستخدمها.

7. تعارض بين المكتبات

رسالة فيها ERESOLVE أو peer dependency. هذي لها درس خاص، لأن الحل السريع فيها له ثمن.

جرّبه على جهازك بنفس طريقة السيرفر

أسرع طريقة تتأكد: جرّب على جهازك بناء نظيف قريب من سيرفر البناء. في مجلد المشروع شغّل npm ci، وهو يثبّت المكتبات من الصفر حسب package-lock.json بالضبط، ثم npm run build. إذا فشل عندك بنفس الرسالة، صار عندك مكان تجرّب فيه بدون ما تنشر كل مرة.

وإذا npm ci نفسه فشل وقال إن package.json و package-lock.json مو متطابقين، Vercel و Netlify غالبًا ما يفشلون بسببه لأنهم يشغّلون npm install، لكنه علامة إن أحد عدّل المكتبات وما رفع الملفين مع بعض، والسيرفر ممكن يثبّت نسخ غير اللي جرّبتها.

الحلول اللي تخفي المشكلة

لما تعطي أداة الذكاء الاصطناعي رسالة الفشل، أحيانًا تقترح واحد من هذي:

• إضافة ignoreBuildErrors: true في إعدادات Next.js، أو إيقاف فحص ESLint وقت البناء في Next.js 15 وما قبله. البناء ينجح، والأخطاء تبقى في الكود وتطلع لعملائك بدل ما تطلع لك.
• حذف package-lock.json وإعادة التثبيت. ممكن ينجح، لكنه يرفع نسخ كل المكتبات مرة وحدة، وتطلع مشاكل جديدة ما تعرف مصدرها.
• إضافة --force أو --legacy-peer-deps. أحيانًا مقبول مؤقتًا، لكن لازم تعرف إيش تخفي.

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

إذا السجل مو مفهوم

انسخ أول خطأ، واحجز مكالمة استشارية: نقرأ السجل معك، ونصلّح السبب بدل ما نخفيه، ويوصلك التسجيل وخطوات مكتوبة. وإذا منتجك من Bolt ويفشل خارجه، شوف مشاكل Bolt الأشهر.