Node.js
npm وإدارة الحزم في Node.js — دليل شامل 2026
📅 2026-11-04⏱ 8 دقائق قراءة
في المقال السابق، تعلمت الوحدات ونظام الملفات. الآن سنتعمق في **npm** — مدير الحزم الذي يجعل Node.js بهذه القوة.
في هذا الدليل العملي، سنأخذك خطوة بخطوة لفهم npm وإدارة الحزم، مع تمارين وحلول.
## ما هو npm؟
**npm** = **Node Package Manager** (مدير حزم Node.js).
**npm** هو:
- **مستودع:** أكبر مستودع حزم في العالم (2+ مليون حزمة).
- **أداة CLI:** لتثبيت وإدارة الحزم.
- **سجل:** يحتوي كل مكتبات JavaScript مفتوحة المصدر.
**تشبيه بسيط:** تخيل أن npm هو **متجر تطبيقات** (مثل App Store):
- تبحث عن تطبيق (مكتبة).
- تثبته (install).
- تحدّثه (update).
- تحذفه (uninstall).
## لماذا npm؟
قبل أن نبدأ، دعنا نتفق على الأسباب:
- **إعادة استخدام:** لا تكتب كل شيء من الصفر.
- **توفير الوقت:** مكتبات جاهزة ومختبرة.
- **الجودة:** مكتبات يستخدمها ملايين المطورين.
- **التحديثات:** صيانة مستمرة.
- **المجتمع:** أكبر مستودع حزم في العالم.
## المفاهيم الأساسية
<table>
<thead>
<tr>
<th>المفهوم</th>
<th>الوصف</th>
</tr>
</thead>
<tbody>
<tr>
<td><strong>Package</strong></td>
<td>مكتبة أو وحدة جاهزة</td>
</tr>
<tr>
<td><strong>package.json</strong></td>
<td>بطاقة تعريف المشروع</td>
</tr>
<tr>
<td><strong>package-lock.json</strong></td>
<td>قفل الإصدارات</td>
</tr>
<tr>
<td><strong>node_modules</strong></td>
<td>مجلد المكتبات المثبتة</td>
</tr>
<tr>
<td><strong>dependencies</strong></td>
<td>مكتبات الإنتاج</td>
</tr>
<tr>
<td><strong>devDependencies</strong></td>
<td>مكتبات التطوير</td>
</tr>
</tbody>
</table>
## إنشاء `package.json`
### الطريقة 1: `npm init` (تفاعلي)
```bash
npm init
```
**سيطلب منك:**
- **name:** اسم المشروع.
- **version:** الإصدار.
- **description:** الوصف.
- **entry point:** نقطة البداية.
- **test command:** أمر الاختبار.
- **git repository:** المستودع.
- **keywords:** الكلمات المفتاحية.
- **author:** المؤلف.
- **license:** الترخيص.
### الطريقة 2: `npm init -y` (سريع)
```bash
npm init -y
```
**النتيجة:**
```json
{
"name": "my-project",
"version": "1.0.0",
"description": "",
"main": "index.js",
"scripts": {
"test": "echo \"Error: no test specified\" && exit 1"
},
"keywords": [],
"author": "",
"license": "ISC"
}
```
## فهم `package.json`
```json
{
"name": "my-app",
"version": "1.0.0",
"description": "تطبيقي الأول",
"main": "index.js",
"scripts": {
"start": "node index.js",
"dev": "nodemon index.js",
"test": "jest"
},
"keywords": ["nodejs", "express"],
"author": "أحمد",
"license": "MIT",
"dependencies": {
"express": "^4.18.2",
"dotenv": "^16.3.1"
},
"devDependencies": {
"nodemon": "^3.0.1",
"jest": "^29.7.0"
}
}
```
### شرح الحقول:
<table>
<thead>
<tr>
<th>الحقل</th>
<th>الوصف</th>
</tr>
</thead>
<tbody>
<tr>
<td><code>name</code></td>
<td>اسم المشروع</td>
</tr>
<tr>
<td><code>version</code></td>
<td>الإصدار (SemVer)</td>
</tr>
<tr>
<td><code>main</code></td>
<td>نقطة البداية</td>
</tr>
<tr>
<td><code>scripts</code></td>
<td>أوامر مخصصة</td>
</tr>
<tr>
<td><code>dependencies</code></td>
<td>مكتبات الإنتاج</td>
</tr>
<tr>
<td><code>devDependencies</code></td>
<td>مكتبات التطوير</td>
</tr>
</tbody>
</table>
## تثبيت الحزم
### 1. تثبيت مكتبة (إنتاج)
```bash
npm install express
```
**أو:**
```bash
npm i express
```
**النتيجة:** تُضاف إلى `dependencies`.
### 2. تثبيت مكتبة (تطوير)
```bash
npm install --save-dev nodemon
```
**أو:**
```bash
npm i -D nodemon
```
**النتيجة:** تُضاف إلى `devDependencies`.
### 3. تثبيت عدة مكتبات
```bash
npm install express cors dotenv mongoose
```
### 4. تثبيت مكتبة عالمياً
```bash
npm install -g typescript
```
**⚠️ نادراً ما تحتاجه.**
### 5. تثبيت نسخة محددة
```bash
npm install [email protected]
```
### 6. تثبيت كل المكتبات
من `package.json`:
```bash
npm install
```
**أو:**
```bash
npm i
```
## حذف الحزم
```bash
# حذف مكتبة
npm uninstall express
# حذف مكتبة تطوير
npm uninstall nodemon
```
## تحديث الحزم
```bash
# عرض المكتبات القديمة
npm outdated
# تحديث مكتبة
npm update express
# تحديث الكل
npm update
```
## رموز الإصدارات (SemVer)
**SemVer** = **Semantic Versioning**.
**الصيغة:** `MAJOR.MINOR.PATCH` (مثل: `1.4.2`).
<table>
<thead>
<tr>
<th>الرمز</th>
<th>المعنى</th>
<th>المثال</th>
</tr>
</thead>
<tbody>
<tr>
<td><code>^</code></td>
<td>تحديث Minor و Patch</td>
<td><code>^1.4.2</code> → 1.x.x</td>
</tr>
<tr>
<td><code>~</code></td>
<td>تحديث Patch فقط</td>
<td><code>~1.4.2</code> → 1.4.x</td>
</tr>
<tr>
<td>بدون</td>
<td>نسخة محددة</td>
<td><code>1.4.2</code></td>
</tr>
<tr>
<td><code>*</code></td>
<td>أي نسخة</td>
<td><code>*</code></td>
</tr>
</tbody>
</table>
**الشرح:**
- **1.4.2 → 1.4.5:** Patch (إصلاح أخطاء).
- **1.4.2 → 1.5.0:** Minor (ميزات جديدة، متوافق).
- **1.4.2 → 2.0.0:** Major (تغييرات كاسرة).
## السكربتات (Scripts)
في `package.json`:
```json
{
"scripts": {
"start": "node index.js",
"dev": "nodemon index.js",
"test": "jest",
"lint": "eslint .",
"build": "tsc"
}
}
```
**التشغيل:**
```bash
npm start # npm run start (اختصار)
npm run dev
npm run test
npm run lint
npm run build
```
**⚠️ ملاحظة:** `start` و `test` لهما اختصارات (`npm start` بدلاً من `npm run start`).
## المكتبات الشائعة
### 1. Express — إطار ويب
```bash
npm install express
```
**الاستخدام:**
```javascript
const express = require("express");
const app = express();
app.get("/", (req, res) => {
res.send("مرحباً!");
});
app.listen(3000);
```
### 2. dotenv — متغيرات البيئة
```bash
npm install dotenv
```
**الاستخدام:**
```javascript
require("dotenv").config();
const PORT = process.env.PORT || 3000;
```
### 3. CORS — السماح بالطلبات
```bash
npm install cors
```
**الاستخدام:**
```javascript
const cors = require("cors");
app.use(cors());
```
### 4. Nodemon — إعادة تشغيل تلقائية
```bash
npm install -D nodemon
```
**الاستخدام:**
```json
"scripts": {
"dev": "nodemon index.js"
}
```
### 5. Mongoose — MongoDB
```bash
npm install mongoose
```
**الاستخدام:**
```javascript
const mongoose = require("mongoose");
await mongoose.connect("mongodb://localhost:27017/mydb");
```
### 6. bcrypt — تشفير كلمات المرور
```bash
npm install bcrypt
```
**الاستخدام:**
```javascript
const bcrypt = require("bcrypt");
const hash = await bcrypt.hash("password", 10);
```
### 7. jsonwebtoken — JWT
```bash
npm install jsonwebtoken
```
**الاستخدام:**
```javascript
const jwt = require("jsonwebtoken");
const token = jwt.sign({ userId: 1 }, "secret");
```
## `.gitignore` — مهم جداً!
**لا ترفع `node_modules`** إلى Git!
**أنشئ `.gitignore`:**
```
node_modules/
.env
*.log
.DS_Store
dist/
build/
coverage/
```
## مجلد `node_modules`
**⚠️ مهم:**
- **لا تعدّله يدوياً.**
- **لا ترفعه لـ Git.**
- **يمكن حذفه وإعادة تثبيته** بـ `npm install`.
**الحجم:** يمكن أن يصل إلى مئات الميجابايت!
## `package-lock.json`
**يحتوي على:**
- الإصدارات الدقيقة لكل مكتبة.
- شجرة التبعيات الكاملة.
**⚠️ مهم:**
- **ارفعها لـ Git.**
- **لا تعدّلها يدوياً.**
- **تضمن نفس الإصدارات لفريق العمل.**
## مثال عملي: مشروع Express
### 1. إنشاء المشروع
```bash
mkdir express-demo
cd express-demo
npm init -y
npm install express dotenv
npm install -D nodemon
```
### 2. إنشاء `.env`
```
PORT=3000
NODE_ENV=development
```
### 3. إنشاء `index.js`
```javascript
require("dotenv").config();
const express = require("express");
const app = express();
const PORT = process.env.PORT || 3000;
app.use(express.json());
app.get("/", (req, res) => {
res.json({ message: "مرحباً من Express!" });
});
app.get("/health", (req, res) => {
res.json({ status: "OK", timestamp: new Date().toISOString() });
});
app.listen(PORT, () => {
console.log(`🚀 السيرفر يعمل على http://localhost:${PORT}`);
});
```
### 4. تعديل `package.json`
```json
"scripts": {
"start": "node index.js",
"dev": "nodemon index.js"
}
```
### 5. التشغيل
```bash
npm run dev
```
**النتيجة:**
```
🚀 السيرفر يعمل على http://localhost:3000
```
افتح المتصفح على `http://localhost:3000` — سترى:
```json
{ "message": "مرحباً من Express!" }
```
**🎉 مبروك! بنيت أول سيرفر Express!**
## تمارين عملية
### تمرين 1: إنشاء مشروع
أنشئ مشروعاً جديداً مع `package.json`.
**الحل:**
```bash
mkdir my-project
cd my-project
npm init -y
```
### تمرين 2: تثبيت مكتبة
ثبّت `lodash` كمكتبة إنتاج.
**الحل:**
```bash
npm install lodash
```
### تمرين 3: تثبيت مكتبة تطوير
ثبّت `nodemon` كمكتبة تطوير.
**الحل:**
```bash
npm install -D nodemon
```
### تمرين 4: السكربتات
أضف سكربت `dev` لتشغيل `nodemon`.
**الحل:**
```json
"scripts": {
"dev": "nodemon index.js"
}
```
### تمرين 5: استخدام lodash
استخدم `lodash` لعكس مصفوفة.
**الحل:**
```javascript
const _ = require("lodash");
const reversed = _.reverse([1, 2, 3, 4, 5]);
console.log(reversed); // [5, 4, 3, 2, 1]
```
### تمرين 6: مشروع Express بسيط
أنشئ مشروع Express مع 3 مسارات.
**الحل:**
```javascript
const express = require("express");
const app = express();
app.get("/", (req, res) => res.send("الرئيسية"));
app.get("/about", (req, res) => res.send("من نحن"));
app.get("/contact", (req, res) => res.send("اتصل بنا"));
app.listen(3000, () => console.log("🚀 يعمل"));
```
### تمرين 7: متغيرات البيئة
استخدم `dotenv` لقراءة `PORT` من `.env`.
**الحل:**
```javascript
require("dotenv").config();
const express = require("express");
const app = express();
const PORT = process.env.PORT || 3000;
app.listen(PORT, () => console.log(`🚀 على ${PORT}`));
```
### تمرين 8: مشروع كامل
أنشئ مشروعاً كاملاً مع Express, dotenv, nodemon.
**الحل:** (راجع المثال العملي أعلاه)
## حل المشاكل الشائعة
### 🔴 المشكلة 1: `npm install` بطيء
**الحل:** استخدم مرآة أسرع:
```bash
npm config set registry https://registry.npmmirror.com
```
**للرجوع:**
```bash
npm config set registry https://registry.npmjs.org
```
### 🔴 المشكلة 2: `EACCES: permission denied`
**الحل (ماك/لينكس):**
```bash
sudo chown -R $(whoami) ~/.npm
```
### 🔴 المشكلة 3: `Cannot find module 'xxx'`
**الحل:**
```bash
npm install
```
### 🔴 المشكلة 4: تعارض الإصدارات
**الحل:**
```bash
rm -rf node_modules package-lock.json
npm install
```
### 🔴 المشكلة 5: `npm ERR! peer dep missing`
**الحل:**
```bash
npm install --legacy-peer-deps
```
## جدول أوامر npm
<table>
<thead>
<tr>
<th>الأمر</th>
<th>الوظيفة</th>
</tr>
</thead>
<tbody>
<tr>
<td><code>npm init -y</code></td>
<td>إنشاء package.json</td>
</tr>
<tr>
<td><code>npm install</code></td>
<td>تثبيت كل المكتبات</td>
</tr>
<tr>
<td><code>npm i <package></code></td>
<td>تثبيت مكتبة</td>
</tr>
<tr>
<td><code>npm i -D <package></code></td>
<td>تثبيت للتطوير</td>
</tr>
<tr>
<td><code>npm i -g <package></code></td>
<td>تثبيت عالمي</td>
</tr>
<tr>
<td><code>npm uninstall <package></code></td>
<td>حذف مكتبة</td>
</tr>
<tr>
<td><code>npm update</code></td>
<td>تحديث المكتبات</td>
</tr>
<tr>
<td><code>npm outdated</code></td>
<td>عرض القديمة</td>
</tr>
<tr>
<td><code>npm list</code></td>
<td>عرض المثبتة</td>
</tr>
<tr>
<td><code>npm run <script></code></td>
<td>تشغيل سكربت</td>
</tr>
</tbody>
</table>
## قائمة تحقق نهائية
<table>
<thead>
<tr>
<th>المهمة</th>
<th>الحالة</th>
</tr>
</thead>
<tbody>
<tr>
<td>إنشاء <code>package.json</code></td>
<td>⬜</td>
</tr>
<tr>
<td>تثبيت مكتبة إنتاج</td>
<td>⬜</td>
</tr>
<tr>
<td>تثبيت مكتبة تطوير</td>
<td>⬜</td>
</tr>
<tr>
<td>فهم SemVer</td>
<td>⬜</td>
</tr>
<tr>
<td>إنشاء سكربتات</td>
<td>⬜</td>
</tr>
<tr>
<td>إنشاء <code>.gitignore</code></td>
<td>⬜</td>
</tr>
<tr>
<td>بناء مشروع Express</td>
<td>⬜</td>
</tr>
<tr>
<td>حل التمارين الثمانية</td>
<td>⬜</td>
</tr>
</tbody>
</table>
## ماذا بعد هذا المقال؟
الآن بعد أن أتقنت npm، أنت جاهز للمقال التالي:
1. **بناء HTTP Server** — أول سيرفر بدون Express.
2. **Express.js** — إطار العمل الكامل.
3. **بناء REST API** — واجهات برمجية.
## الخلاصة
في هذا المقال، تعلمت:
- ✅ ما هو npm ولماذا نحتاجه.
- ✅ إنشاء `package.json`.
- ✅ تثبيت وحذف وتحديث الحزم.
- ✅ رموز الإصدارات (SemVer).
- ✅ السكربتات (Scripts).
- ✅ المكتبات الشائعة.
- ✅ `.gitignore` و `node_modules`.
- ✅ بناء مشروع Express.
- ✅ حل 8 تمارين عملية.
**تذكر:** npm هو **سلاحك السري** في Node.js. أتقنه جيداً.