Node.js: مدير حزم npm

آخر تحديث: 2026-08-26

كانت أليس قد بدأت للتو في العمل على مشروع جديد يتطلب إضافة مكتبة Luxon لمعالجة التواريخ وإطار عمل Express لـ HTTP، بالإضافة إلى تهيئة أداة الاختبار Jest. في البداية، قامت بتنزيل ملفات JavaScript واحدًا تلو الآخر من المواقع الرسمية لكل منها ونسخها يدويًّا إلى مشروعها، لكنها كانت تواجه باستمرار تعارضات في الإصدارات، وكانت عملية الترقية بمثابة كابوس. استمر الوضع على هذا النحو إلى أن عرّفها أحد زملائها على npm — وهو أمر واحد لتثبيت التبعيات، حيث يتم تسجيل الإصدارات في パッケージ.json وتثبيتها على الإصدارات المحددة عبر ملف ロック. ومنذ ذلك الحين، لم يواجه الفريق أبدًا مشكلة «إنه يعمل على جهازي» مرة أخرى.

ستتعلم:

• استخدم npm init وnpm install وnpm uninstall لإدارة تبعيات المشروع
• التمييز بين «التبعيات» و«devDependencies» وحالات استخدام كل منهما
• فهم الغرض من パッケージ-ロック.json واستراتيجية コミット
• فهم قواعد الترقيم الدلالي في SemVer (^، ~، >=، إلخ)
• تعزيز كفاءة التطوير باستخدام نصوص npm و npx

1. npm init — تهيئة مشروع

(1) التهيئة التفاعلية

عند تشغيل npm init، سيُطلب منك إدخال معلومات المشروع خطوة بخطوة، ليتم في النهاية إنشاء パッケージ.json.

▶ مثال: إنشاء ملف package.json تفاعليًّا

mkdir my-project && cd my-project
npm init

package name: (my-project)
version: (1.0.0)
description: A sample project
entry point: (index.js)
test command: jest
git repository:
keywords:
author: Alice
license: (ISC)

(2) التهيئة السريعة

استخدم -y لتخطي جميع المطالبات وإنشاء package.json الافتراضي.

▶ مثال: تخطي المطالبات لإنشاء النص بسرعة

npm init -y

Wrote to /home/alice/my-project/package.json

المحتوى الافتراضي الذي تم إنشاؤه パッケージ.json:

{
  "name": "my-project",
  "version": "1.0.0",
  "description": "",
  "main": "index.js",
  "scripts": {
    "test": "echo \"Error: no test specified\" && exit 1"
  },
  "license": "ISC"
}

2. npm install / uninstall — تثبيت التبعيات وإزالتها

(1) تثبيت المكونات التبعية

npm install <package> قم بتنزيل الحزمة إلى node_modules وانسخها إلى package.json.

▶ مثال: تثبيت التبعيات الخاصة بالإنتاج

npm install express

(2) تثبيت التبعيات الخاصة بالتطوير

--save-dev (يُشار إليه اختصارًا بـ -D) يقوم بتسجيل الحزم في devDependencies، وهو مخصص للاستخدام في بيئات التطوير فقط.

▶ مثال: تثبيت التبعيات الخاصة بالتطوير

npm install jest --save-dev

(3) إلغاء تثبيت التبعيات

npm uninstall احذف كلا الملفين الموجودين في node_modules والسجلات الموجودة في package.json.

▶ مثال: إلغاء تثبيت أحد المكونات التابعة

npm uninstall express

(4) تثبيت جميع المكونات التابعة

بعد استنساخ مشروع شخص آخر، قم بتشغيل npm install لاستعادة جميع التبعيات باستخدام package.json وpackage-lock.json.

▶ مثال: استعادة التبعيات

npm install

3. التبعيات مقابل devDependencies

(1) تصنيف التبعية

dependencies يسرد الحزم المطلوبة لبيئة الإنتاج؛ devDependencies يسرد الحزم المستخدمة فقط خلال مرحلة التطوير.

▶ مثال: أقسام التبعيات في ملف package.json

{
  "dependencies": {
    "express": "^4.18.2",
    "luxon": "^3.4.4"
  },
  "devDependencies": {
    "jest": "^29.7.0",
    "eslint": "^8.56.0"
  }
}

(2) تخطي تبعيات التطوير أثناء التثبيت في بيئة الإنتاج

استخدم --production أو اضبط NODE_ENV=production لتخطي تثبيت devDependencies وتقليل حجم النشر.

▶ مثال: التثبيت في بيئة الإنتاج

npm install --production

4. الغرض من ملف package-lock.json

(1) تحديد الإصدار بالضبط

パッケージ-ロック.json قم بتسجيل الإصدار الدقيق ورمز التجزئة الخاص بسلامة كل تابع لضمان اتساق نتائج التثبيت في جميع البيئات.

(2) تحسين سرعة التثبيت

يحتوي الملف ロック على شجرة التبعيات الكاملة، مما يسمح لـ npm بتخطي عملية تحديد الإصدارات وتنزيل الحزم مباشرةً.

▶ مثال: مقتطف من ملف «ロック»

{
  "node_modules/luxon": {
    "version": "3.4.4",
    "resolved": "https://registry.npmjs.org/luxon/-/luxon-3.4.4.tgz",
    "integrity": "sha512-zaBViHBuQffgP8h...',
    "requires": {}
  }
}

5. الترقيم الدلالي (SemVer)

(1) تنسيق رقم الإصدار

تنسيق SemVer هو MAJOR.MINOR.PATCH، حيث لكل مكون معنى محدد.

(2) رموز نطاق الإصدارات

استخدم الرموز الموجودة في package.json لتحديد نطاق الإصدارات المقبولة.

▶ مثال: النتائج الفعلية لمختلف النطاقات

{
  "express": "^4.18.2",
  "lodash": "~4.17.21",
  "axios": ">=1.6.0",
  "デバッグ": "4.3.x"
}

(3) قواعد تحديث الإصدارات

• التحديث: يُصلح الأخطاء دون تغيير واجهة برمجة التطبيقات (API)
• MINOR (إصدار ثانوي): ميزات جديدة، متوافق مع الإصدارات السابقة
• MAJOR (الإصدار الرئيسي): تغييرات متوافقة مع الإصدارات الأحدث؛ غير متوافقة مع الإصدارات الأقدم

6. التثبيت العام مقابل التثبيت المحلي

(1) التثبيت المحلي

بشكل افتراضي، يتم تثبيت الحزمة في مشروع node_modules؛ ويمكن للمشاريع المختلفة استخدام إصدارات مختلفة.

(2) التثبيت الشامل

أضف العلامة -g لتثبيت الحزمة في الدليل العام للنظام وتوفير أداة لسطر الأوامر.

▶ مثال: تثبيت أداة سطر الأوامر على مستوى النظام

npm install -g nodemon

(3) متى يتم استخدام التثبيت الشامل

قم بتثبيت الأدوات التي تتطلب الوصول إلى سطر الأوامر فقط (مثل nodemon و pm2)؛ أما تبعيات المشروع فيجب تثبيتها محليًّا دائمًا.

7. نصوص npm

(1) البرامج النصية المدمجة

start وtest هما نصوص برمجية مدمجة في npm يمكن تشغيلها مباشرةً باستخدام npm start / npm test.

(2) البرامج النصية المخصصة

يجب تنفيذ البرامج النصية الأخرى باستخدام npm run <name>.

▶ مثال: تكوين البرامج النصية الشائعة

{
  "scripts": {
    "start": "node index.js",
    "dev": "nodemon index.js",
    "test": "jest --coverage",
    "lint": "eslint src/"
  }
}

npm start
npm run dev
npm test
npm run lint

(3) الروابط بين البرامج النصية

يتم تنفيذ pre<script> وpost<script> تلقائيًا قبل البرنامج النصي المستهدف وبعده.

▶ مثال: استخدام الخطاف pre

{
  "scripts": {
    "prebuild": "npm run lint",
    "build": "node build.js",
    "postbuild": "echo Build complete"
  }
}

سيؤدي تشغيل npm run build إلى تنفيذ prebuild → build → postbuild تباعًا.

8. الأمر npx

(1) تنفيذ حزمة عن بُعد مؤقتًا

npx يتيح لك تشغيل الحزم التي لم يتم تثبيتها مباشرةً، مما يمنع التلوث العام.

▶ مثال: استخدام create-react-app بشكل مؤقت

npx create-react-app my-app

(2) تشغيل أمر على نظام مُثبَّت محليًّا

سيقوم npx أولاً بالبحث عن node_modules/.bin محليًّا، ثم عالميًّا، وأخيرًا سيقوم بتنزيله عن بُعد.

▶ مثال: تشغيل أداة محلية

npx jest

(3) تشغيل إصدار معين

▶ مثال: استخدام إصدار معين من حزمة ما

npx express-generator@4 --view=ejs my-site

9. تهيئة ملف .npmrc

(1) التسلسل الهرمي لملفات التكوين

.npmrc يدعم ثلاثة مستويات: مستوى المشروع، ومستوى المستخدم، والمستوى العام، مرتبة حسب الأولوية من الأعلى إلى الأسفل.

▶ مثال: تكوين مصادر النسخ المتطابق في ملف .npmrc على مستوى المشروع

registry=https://registry.npmmirror.com

(2) خيارات التكوين الشائعة

▶ مثال: ضبط الإعدادات باستخدام أمر

npm config set registry https://registry.npmmirror.com
npm config get registry
npm config list

10. عملية تنفيذ الأمر "npm install"

flowchart TD
    A[npm install] --> B{Does it exist? package-lock.json?}
    B -- Yes --> C[Read lock The exact version in the document]
    B -- No --> D[Analysis package.json Version range in]
    D --> E[Search registry Get the latest compatible version]
    E --> F[Generate a dependency tree]
    C --> G[Download the package to the cache]
    F --> G
    G --> H[Write node_modules Table of Contents]
    H --> I[Update package-lock.json]
    I --> J[Installation Complete]

flowchart TD
    A[npm install] --> B{Does it exist? package-lock.json?}
    B -- Yes --> C[Read lock The exact version in the document]
    B -- No --> D[Analysis package.json Version range in]
    D --> E[Search registry Get the latest compatible version]
    E --> F[Generate a dependency tree]
    C --> G[Download the package to the cache]
    F --> G
    G --> H[Write node_modules Table of Contents]
    H --> I[Update package-lock.json]
    I --> J[Installation Complete]

11. مثال شامل: إعداد تبعيات المشروع من البداية

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

mkdir alice-server && cd alice-server
npm init -y

npm install express luxon
npm install jest nodemon --save-dev

パッケージ.json بعد التثبيت:

{
  "name": "alice-server",
  "version": "1.0.0",
  "description": "Alice's date-aware HTTP server",
  "main": "index.js",
  "scripts": {
    "start": "node index.js",
    "dev": "nodemon index.js",
    "test": "jest"
  },
  "dependencies": {
    "express": "^4.18.2",
    "luxon": "^3.4.4"
  },
  "devDependencies": {
    "jest": "^29.7.0",
    "nodemon": "^3.0.2"
  },
  "license": "ISC"
}

إنشاء ملف الإدخال index.js:

const express = require('express');
const { DateTime } = require('luxon');

const app = express();
const PORT = 3000;

app.get('/', (req, res) => {
  const now = DateTime.now().toISO();
  res.json({ message: 'Server is running', timestamp: now });
});

app.listen(PORT, () => {
  console.log(`Server listening on port ${PORT}`);
});

ابدأ تشغيل خادم التطوير:

npm run dev

[nodemon] starting node index.js
Server listening on port 3000

❓ أسئلة شائعة

📖 ملخص

• استخدم npm init لتهيئة المشروع؛ واستخدم -y لتخطي المطالبات
• التثبيت/إلغاء التثبيت وإدارة التبعيات، ويؤدي استخدام الخيار -D إلى كتابة التبعيات في devDependencies
• يحدد ملف package-lock.json الإصدارات المحددة؛ ويجب تسجيله في سجل التغييرات
• يستخدم SemVer الرموز ^/~/>= للتحكم في نطاقات الإصدارات
• عمليات التثبيت العالمية مخصصة لأدوات واجهة سطر الأوامر (CLI) فقط؛ ويجب تثبيت جميع تبعيات المشروع محليًّا.
• تعمل نصوص npm على تبسيط الأوامر الشائعة؛ ويمكن الاستغناء عن "start" و"test" واستخدام "run" بدلاً منهما
• npx: تشغيل الحزم البعيدة مؤقتًا دون الحاجة إلى تثبيت عام
• يدعم ملف .npmrc ثلاثة مستويات من التكوين: مستوى المشروع، ومستوى المستخدم، والمستوى العام

📝 تمارين

1. قم بتشغيل npm init -y لإنشاء مشروع، ثم قم بتعديل الاسم والوصف والنصوص البرمجية يدويًّا في ملف package.json
2. قم بتثبيت express وluxon كمتطلبات، وقم بتثبيت jest كـ devDependency، ثم لاحظ التغييرات التي طرأت على ملف package.json
3. استخدم npm list وnpm outdated للتحقق من حالة التبعية، على التوالي
4. قم بإنشاء الملف .npmrc، واضبط السجل على https://registry.npmmirror.com، ثم أعد التثبيت للتحقق.
5. اكتب برنامجًا نصيًّا مخصصًا hello يعرض الرسالة "Hello from npm scripts"، وقم بتشغيله باستخدام npm run hello

فريق Web-Tutorial التقني

منصة دروس برمجية يديرها عدة مطورين. كل درس يتم كتابته ومراجعته بواسطة مطورين متخصصين في المجال. نعمل على ضمان دقة وموثوقية المحتوى — إذا لاحظت أي مشكلة، فيرجى إخبارنا.

من نحن