حل خطأ localhost refused to connect بالعربي

كتبت npm run dev (أو ظننت أنك كتبتها 😄)، فتحت المتصفح، فصفعك:

This site can't be reached
localhost refused to connect.
ERR_CONNECTION_REFUSED

أول جدار يصطدم به كل من يشغّل مشروعه الأول محليًا. الخبر الجيد: هذا أصدق خطأ في الويب — معناه حرفيًا: «طرقتُ المنفذ، لا أحد يستمع خلفه».

افهم الرسالة أولًا

عندما تفتح localhost:3000 يحاول المتصفح الاتصال بخادم على منفذ 3000 في جهازك نفسه. الرفض الفوري (refused) يعني أن نظام التشغيل ردّ: «لا يوجد أي برنامج يستمع هنا». لا علاقة للإنترنت ولا للواي فاي — الرحلة كلها داخل جهازك.

قارنه بجيرانه: 404 و500 يعنيان أن خادمًا موجودًا وردّ — أما هنا فلا خادم أصلًا.

الأسباب الخمسة بالترتيب الواقعي

1) الخادم ببساطة غير شغّال

الطرفية أُغلقت، أو أوقفته بـ Ctrl+C ونسيت، أو فتحت نافذة جديدة وظننت القديمة تعمل. العلامة القاطعة: طرفية الخادم يجب أن تعرض سطرًا حيًّا مثل:

✓ Ready on http://localhost:3000

لا سطر؟ لا خادم — شغّله وابقِ الطرفية مفتوحة.

2) انهار أثناء الإقلاع — والجواب فوق مباشرة

شغّلته فعلًا، لكنه مات خلال ثانية برسالة حمراء لم تقرأها. أشهر رسالتين:

• EADDRINUSE — المنفذ محجوز من تشغيلة قديمة: دليلها الكامل هنا.
• Cannot find module ... — اعتماديات ناقصة: npm install ثم أعد التشغيل (التفاصيل).

القاعدة: اقرأ آخر 10 أسطر في الطرفية قبل فتح المتصفح.

3) المنفذ غير الذي تظن

كثير من الأدوات تبدّل المنفذ تلقائيًا عندما يكون الافتراضي محجوزًا:

⚠ Port 3000 is in use, using available port 3001 instead.

وأنت ما زلت تفتح 3000. الحل: انسخ الرابط من الطرفية نفسها — لا تكتبه من الذاكرة.

4) يعمل داخل Docker — والباب مغلق للمضيف

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

docker run -p 3000:3000 my-app   # المضيف:الحاوية

وتذكّر داخل الحاوية أن يستمع تطبيقك على 0.0.0.0 لا على 127.0.0.1 — وإلا رفض الاتصالات الآتية من خارج الحاوية حتى مع النشر. (وتعارضات المنفذ نفسها؟ دليل Docker هنا.)

5) localhost مقابل 127.0.0.1

حالات نادرة لكنها محيّرة: الخادم يستمع على IPv4 (127.0.0.1) والنظام يحل localhost إلى IPv6 (::1) أولًا. جرّب http://127.0.0.1:3000 مباشرة — إن عمل، ثبّت host الخادم أو استخدم الرقم مباشرة.

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

• الطرفية تعرض سطر Ready/Listening الآن؟
• إن مات عند الإقلاع: اقرأ الخطأ — EADDRINUSE أو module ناقص غالبًا.
• انسخ الرابط والمنفذ من الطرفية حرفيًا.
• Docker؟ → -p للنشر + استماع على 0.0.0.0 داخل الحاوية.
• جرّب 127.0.0.1 بدل localhost قبل اتهام أي شيء آخر.

الخلاصة

refused to connect لا يكذب: لا خادم يستمع حيث تطرق. الحل دائمًا في جهة التشغيل — شغّل، اقرأ الطرفية، طابق المنفذ، وانشر منفذ Docker — ولن تراه مجددًا إلا عن نسيان مشروع 😄

أساسيات الخوادم والمنافذ من الجذور في مسار الشبكات بالعربي ومسار Node.js، وأكمل السلسلة مع حل EADDRINUSE.