المنافذ و localhost

💡 دليل التعلم: عندما تنفذ npm run dev وتظهر http://localhost:5173 في الطرفية، هل تساءلت يوماً: ما هو localhost؟ وماذا يعني 5173؟ ولماذا يظهر أحياناً خطأ EADDRINUSE؟ يشرح هذا الفصل دفعة واحدة هذه المفاهيم التي تراها يومياً في التطوير لكن نادراً ما تتعمق فيها.

قبل البدء، يُنصح بمراجعة أساسيين:

• أساسيات الشبكات: إذا لم تكن واضحاً حول مفاهيم عنوان IP و HTTP، يمكنك مراجعة أساسيات الحاسوب - اتصالات الشبكة.
• أساسيات الطرفية: إذا لم تكن ملمّاً بأوامر الطرفية، راجع سطر الأوامر وسكربتات Shell.

---

0. مقدمة: ما هو حقاً ذلك localhost:5173 الذي تراه كل يوم؟

1

2

3

4

5

1. You run npm run dev

Terminal

$ npm run dev

> vite

  准备就绪...

Listening↕

Browser

等待你打开Browser...

💡 You type the start command in terminal

What is an HTTP Server?

🏪

Imagine a service windowHTTP 服务器就像一个"永远开着的服务窗口"——它一直等在那里，有人来问就回答，没人来就静静等着。

📋

Only understands one "code"这个窗口只听得懂 HTTP 协议的请求格式（比如 GET /index.html），然后把对应的文件内容返回给你。

⚙️

Dev Server = Enhanced WindowVite、Webpack 的开发服务器不只是"原样返回文件"，它还会即时编译你的代码（Vue → JS、TS → JS、Sass → CSS），然后再返回给Browser。

One-line Summary:Dev server = An HTTP server running on localhost + Real-time code compiler. It listens on a port, and when browser requests, it returns the compiled code.

يوم كل مطور لا يخلو من سطر المخرجات هذا:

➜  Local:   http://localhost:5173/

لكن هل فكرت أن هذا السطر القصير يخفي عدة مفاهيم رئيسية:

• http:// → بروتوكول الاتصال (أي "لغة" تستخدم في الحوار)
• localhost → عنوان الوجهة (من تبحث عنه)
• :5173 → رقم المنفذ (بعد الوصول، أي باب تطرقه)

فهم هذه الأشياء الثلاثة يجعلك تفهم 90% من مشاكل الشبكة في بيئة التطوير. لنحللها واحداً تلو الآخر.

---

1. ما هو المنفذ (Port)؟ (IP هو المبنى، والمنفذ هو رقم الغرفة)

1.1 تشبيه حدسي

تخيل أن الخادم هو مبنى:

• عنوان IP (مثل 192.168.1.100) هو عنوان المبنى — يخبرك "إلى أي مبنى تذهب".
• رقم المنفذ (مثل :80) هو رقم الغرفة في المبنى — يخبرك "أي غرفة تدخل".

مبنى واحد يمكن أن يحتوي في نفس الوقت على مطعم (غرفة 80)، ومقهى (غرفة 443)، ومكتب (غرفة 22). وبالمثل، حاسوب واحد يمكنه تشغيل خادم ويب، وقاعدة بيانات، وخدمة SSH، كلٌّ يشغل منفذاً مختلفاً.

👇 جرّب: انقر على "لوحات الغرف" أدناه لمحاكاة الاتصال بمنافذ مختلفة. لاحظ ماذا يحدث عندما يكون المنفذ "مفتوحاً" (برنامج يستمع) و"مغلقاً".

Select a "building":

Web Server BuildingIP: 192.168.1.100

80

HTTPWeb access entry

🟢 Listening

443

HTTPSEncrypted web entry

🟢 Listening

22

SSHRemote management channel

🟢 Listening

3306

MySQLDatabase (closed)

🔴 Closed

Core Analogy:IP 地址 = 大楼地址，端口号 = 房间门牌号。一台电脑上可以同时运行多个服务，每个服务"占用"一个端口号，就像同一栋大楼里的不同房间。

1.2 نطاق قيم المنافذ

رقم المنفذ هو عدد صحيح بين 0 و 65535 (65536 منفذاً إجمالاً). تُقسم هذه المنافذ إلى ثلاثة نطاقات:

النطاق	المدى	الاستخدام	مثال
منافذ النظام	0 – 1023	محجوزة للبروتوكولات القياسية؛ المستخدم العادي لا يمكنه استخدامها بحرية	80 (HTTP)، 443 (HTTPS)، 22 (SSH)
منافذ مسجلة	1024 – 49151	للتطبيقات الشائعة المسجلة	3306 (MySQL)، 5432 (PostgreSQL)، 6379 (Redis)
منافذ ديناميكية	49152 – 65535	يخصصها نظام التشغيل مؤقتاً	المتصفح عند إرسال طلب يخصص منفذاً مصدرياً عشوائياً

لماذا يفضل خادم التطوير الخاص بك 3000 و 5173 و 8080؟ لأنها كلها في نطاق "المنافذ المسجلة"، ولا تحتاج صلاحيات مسؤول للاستماع، ونادراً ما تتعارض مع خدمات النظام.

1.3 مرجع سريع للمنافذ الشائعة في التطوير

👇 جرّب: أدخل رقم منفذ أو اسم خدمة للبحث، وانقر على أي سطر لتوسيع مثال الاستخدام.

🔍

PortServiceDescriptionExposure Risk

80HTTP网页访问（未加密）安全

443HTTPS网页访问（加密）安全

22SSH安全远程登录注意

21FTP文件传输敏感

3306MySQLMySQL 数据库敏感

5432PostgreSQLPostgreSQL 数据库敏感

27017MongoDBMongoDB 数据库敏感

6379RedisRedis 缓存敏感

3000Node/ReactNode.js / React 开发服务器安全

5173ViteVite 开发服务器安全

8080通用 HTTPHTTP 备用端口 / 代理安全

8000Django/PythonDjango / Python HTTP 服务安全

5000FlaskFlask 开发服务器安全

4200AngularAngular 开发服务器安全

53DNS域名解析注意

25SMTP邮件发送注意

0 – 1023

System PortsReserved for standard services (HTTP, SSH, etc.), regular users cannot occupy.

1024 – 49151

Registered PortsFor common applications (MySQL 3306, Redis 6379, etc.), most encountered in development.

49152 – 65535

Dynamic PortsTemporarily assigned by OS, like when your browser makes requests, system randomly assigns one.

Security Alert:数据库端口（3306、5432、27017、6379）绝对不要直接暴露到公网！生产环境应只允许内网访问或通过 SSH 隧道连接。

---

2. ما هو localhost؟ (إيجاد النفس)

2.1 المفهوم الأساسي لـ "الاسترجاع"

localhost هو اسم نطاق خاص يشير دائماً إلى حاسوبك نفسه.

عندما تكتب http://localhost:3000 في المتصفح، تحدث هذه الأشياء:

1. المتصفح يسأل نظام التشغيل: "ما عنوان IP لـ localhost؟"
2. نظام التشغيل يجيب مباشرة: "127.0.0.1" (لا يحتاج للاستعلام من DNS)
3. تُرسل الحزمة إلى 127.0.0.1، لكنها لا تغادر الجهاز فعلياً
4. نظام التشغيل عبر "واجهة الاسترجاع (loopback interface)" يُعيد الحزمة بالاتجاه المعاكس
5. البرنامج المستمع على المنفذ 3000 يتلقى الطلب ويعيد الاستجابة

كل العملية لا تمر عبر كابل شبكة، ولا موجه، ولا تحتاج اتصال إنترنت.

👇 جرّب: انقر على "إرسال طلب" وراقب الرحلة الكاملة للحزمة. ثم انقر على "بطاقات التنكر" أدناه لفهم أشكال localhost المختلفة وفروقاتها.

🔗

🌐

BrowserYou enter URL in address bar

→

📖

DNS Resolutionlocalhost → 127.0.0.1 (no internet)

→

🔄

Network LayerPacket sent to 127.0.0.1 (loopback interface)

→

⚙️

Local ServiceProgram on port 3000 receives request

→

📨

Return Response{ "message": "Hello!" }

Your App(Browser)

Request stays on local machine

Local Service(:3000)

Localhost "Aliases" (click to see description)

localhost→ 127.0.0.1

127.0.0.1→ 127.0.0.1

::1→ ::1

0.0.0.0→ 0.0.0.0

This is mapped in your computer's <code>/etc/hosts</code> file. When browser sees <code>localhost</code>, it directly resolves to <code>127.0.0.1</code> without asking DNS server.： 这是写在你电脑 /etc/hosts 文件里的映射。浏览器看到 localhost 时，直接解析为 127.0.0.1，不会去问 DNS 服务器。

Core Concept:localhost 就是"自己找自己"。数据包通过环回接口（loopback interface）在本机内部折返，不经过网线、不经过路由器，速度极快且完全安全。

2.2 localhost مقابل 127.0.0.1 مقابل 0.0.0.0

هذه المفاهيم الثلاثة كثيراً ما تُخلط، لكن معانيها مختلفة تماماً:

الكتابة	المعنى	من يمكنه الوصول
localhost / 127.0.0.1	عنوان استرجاع، الجهاز المحلي فقط	حاسوبك فقط
0.0.0.0	الاستماع على جميع واجهات الشبكة	الجهاز المحلي + أجهزة أخرى في الشبكة المحلية
192.168.x.x	IP الشبكة المحلية	الأجهزة في الشبكة المحلية

سيناريوهات عملية:

# فقط أنت تستطيع الوصول (آمن، مناسب للتطوير)
npm run dev -- --host localhost

# هاتفك يستطيع الوصول أيضاً (مناسب لاختبار الجوال)
npm run dev -- --host 0.0.0.0

كثير من الأُطر (مثل Vite و Next.js) تستمع على localhost افتراضياً، لذلك هاتفك حتى لو كان على نفس WiFi لن يستطيع الوصول. تريد اختبار الجوال؟ أضف معامل --host.

---

3. تعارض المنافذ: أكثر مشاكل بيئة التطوير شيوعاً

3.1 لماذا تحدث التعارضات؟

منفذ واحد لا يمكن أن يستمع عليه إلا برنامج واحد في نفس الوقت. مثل غرفة لا يسكنها إلا أسرة واحدة.

إذا حاولت تشغيل خدمة ثانية على نفس المنفذ، سترى هذا الخطأ الكلاسيكي:

Error: listen EADDRINUSE :::3000

بالعربي: "الغرفة 3000 مشغولة، لا يمكنك الدخول!"

سيناريوهات التعارض الشائعة:

• خادم التطوير السابق لم يُغلق بشكل نظيف وما زال يعمل في الخلفية
• مشروعان مختلفان يستخدمان نفس المنفذ الافتراضي
• خدمة نظام تشغل بالفعل المنفذ الذي تريده

👇 جرّب: حاول تشغيل الخدمات عدة مرات في المحاكي أدناه. عند تعارض المنافذ، قارن بين المعالجة المختلفة لـ "التشغيل المباشر" و"التشغيل الذكي".

Try starting:React(default port 5173)

Currently Running Services1 services

Vite:5173🟢 Running

Port Conflict:一个端口同一时刻只能被一个程序监听。如果你看到 EADDRINUSE 错误，说明这个端口已经被占了。要么杀掉旧进程，要么换个端口。

3.2 التشخيص والحل

عندما يحدث تعارض منافذ، عملية التشخيص ثابتة جداً:

macOS / Linux:

# الخطوة 1: معرفة من يشغل المنفذ 3000
lsof -i :3000

# الخطوة 2: بالـ PID، إنهاء العملية قسراً
kill -9 <PID>

Windows:

# الخطوة 1: معرفة من يشغل المنفذ 3000
netstat -ano | findstr :3000

# الخطوة 2: إنهاء العملية
taskkill /PID <PID> /F

كثير من الأُطر الحديثة (Vite، Create React App، إلخ) عند تعارض المنافذ تسأل تلقائياً "هل تريد تبديل المنفذ؟". لكن فهم المبادئ الأساسية يساعدك على الحل أسرع في الحالات التي لا يستطيع الإطار مساعدتك فيها.

---

4. "سياسة نفس الأصل" و CORS في التطوير

4.1 ما هو "الأصل"؟

للمتصفح آلية أمان تُسمى سياسة نفس الأصل (Same-Origin Policy): فقط عندما يتطابق البروتوكول، والنطاق، والمنفذ تماماً يُعتبر "نفس الأصل".

العنوان أ	العنوان ب	نفس الأصل؟	السبب
http://localhost:5173	http://localhost:5173/about	✅ نفس الأصل	البروتوكول والنطاق والمنفذ متماثلة
http://localhost:5173	http://localhost:3000	❌ أصل مختلف	المنفذ مختلف (5173 مقابل 3000)
http://localhost:5173	https://localhost:5173	❌ أصل مختلف	البروتوكول مختلف (http مقابل https)

4.2 لماذا يؤدي فصل الواجهة الأمامية/الخلفية حتماً إلى CORS؟

عندما تكون بنية مشروعك:

الواجهة الأمامية (Vite)  →  http://localhost:5173
الخلفية (Express) →  http://localhost:3000

صفحة الواجهة الأمامية تُحمَّل من :5173 ثم تستخدم fetch('/api/users') لطلب الواجهة على :3000 — المنفذ مختلف، فتُفعّل قيود CORS!

حلان شائعان:

الحل 1: تهيئة CORS في الخلفية

// Express backend
app.use(cors({ origin: 'http://localhost:5173' }))

الحل 2: تهيئة وسيط في الواجهة الأمامية (موصى به)

// vite.config.js
export default {
  server: {
    proxy: {
      '/api': 'http://localhost:3000'
    }
  }
}

مبدأ الوسيط: خادم تطوير Vite "يعيد توجيه" الطلبات نيابة عنك. المتصفح يعتقد أنه يتواصل مع :5173 (نفس الأصل)، لكن في الواقع Vite يعيد توجيه الطلبات سراً إلى :3000.

---

5. استكشاف عملي: ثلاثة أشهر المشاكل شيوعاً

👇 جرّب: اختر مشكلة واجهتها واتبع الخطوات معاً. كل خطوة يمكن النقر على "تنفيذ" لرؤية المخرجات.

Select a common issue:

🔴

Port OccupiedError: listen EADDRINUSE :::3000

Troubleshooting Steps (1/3)

$lsof -i :3000

Check who is using this port

Troubleshooting Mantra:先确认服务有没有启动（lsof / netstat），再确认端口对不对，最后确认是不是跨域问题。90% 的 localhost 问题都逃不出这三步。

---

6. جدول المصطلحات

المصطلح بالإنجليزية	المقابل	الشرح
Port	منفذ	رقم بين 0 و 65535 يميز خدمات الشبكة المختلفة على نفس الجهاز. كل خدمة "تستمع" على منفذ وتنتظر اتصال العملاء.
localhost	المضيف المحلي	اسم نطاق خاص يشير دائماً للجهاز المحلي (127.0.0.1). يُستخدم للوصول للخدمات المحلية بدون إنترنت.
Loopback Interface	واجهة الاسترجاع	واجهة شبكة افتراضية في نظام التشغيل. الحزم المرسلة لـ 127.0.0.1 لا تغادر الجهاز بل تُعاد عبر هذه الواجهة.
EADDRINUSE	العنوان مستخدم	خطأ من Node.js / نظام التشغيل يعني أن المنفذ الذي تريد الاستماع عليه يشغله برنامج آخر.
CORS	مشاركة الموارد عبر الأصل	آلية أمان في المتصفح. عند محاولة صفحة الواجهة الأمامية طلب واجهة من أصل مختلف (بروتوكول/نطاق/منفذ مختلف)، يجب أن يسمح الخادم صراحةً.
Same-Origin Policy	سياسة نفس الأصل	حجر أساس أمان المتصفح: يسمح فقط بالاتصال الحر بين نفس البروتوكول والنطاق والمنفذ، ويمنع قراءة البيانات عبر الأصول المختلفة.
Proxy	وسيط	في بيئة التطوير، خادم الوسيط يعيد توجيه الطلبات للخلفية بدلاً من المتصفح، متجاوزاً قيود نفس الأصل.
0.0.0.0	جميع الواجهات	عندما تستمع خدمة على 0.0.0.0، فهي تقبل اتصالات من أي واجهة شبكة (محلي، شبكة محلية، إلخ).
Well-known Ports	المنافذ المعروفة	اسم جماعي للمنافذ 0–1023، محجوزة للبروتوكولات القياسية مثل HTTP (80)، HTTPS (443)، SSH (22).
PID	معرّف العملية	رقم فريد يخصصه نظام التشغيل لكل برنامج قيد التشغيل، لإدارة العمليات وإنهائها.
lsof	سرد الملفات المفتوحة	أمر في macOS/Linux لمعرفة أي عملية تشغل منفذاً معيناً (lsof -i :port).
HMR	استبدال الوحدات الساخن	ميزة خادم التطوير: عند تعديل الكود، يُحدّث المتصفح تلقائياً دون تحديث يدوي. يعمل عبر WebSocket.

---

الخلاصة

المنافذ و localhost هي المفاهيم الأكثر أساسية والأكثر تكراراً في بيئة التطوير:

• المنفذ = "رقم الغرفة" لتمييز الخدمات على نفس الجهاز (0–65535)
• localhost = العنوان الخاص بـ "إيجاد النفس" (127.0.0.1)، البيانات لا تغادر الجهاز
• تعارض المنافذ جوهره "غرفة واحدة لا يُعلّق عليها إلا لافتة واحدة"
• CORS جوهره "منفذ مختلف = أصل مختلف"، يحتاج CORS أو وسيط للحل

تذكر هذه الجمل الأربع، ومعظم مشاكل الشبكة في بيئة التطوير يمكنك تحديد أسبابها بسرعة.