لا تحب الإعلانات؟ يذهب خالية من الإعلانات اليوم 

النسخة المعنوية نظام التصنيف الذي يعتمد عليه تثبيت npm

تحديث في 4 يونيو 2026

أرقام سيمفري تشكل عقدًا. تغييرات كبيرة تُحدث تغييرات جذرية، تغييرات صغيرة تضيف ميزات، تغييرات بسيطة تصلح الأخطاء — وعندما ينهار بناءك بعد تثبيت npm، فإن هذا يحدث في تسع من عشرة أوقات لأن شخصًا ما تجاهل هذا العقد. إليك كيف يعمل نظام العد، وماذا يعني ^ و~ في ملف package.json، ولماذا يجب أن تُحفظ ملفات التثبيت بشكل دائم.

النسخة المعنوية: نظام التصنيف الذي يعتمد عليه تثبيت npm 1

إعلان · حذف؟

بناءك فشل. عمل على يوم الجمعة. npm install في يوم الاثنين تم استلامه react-query@5 والآن نصف ملحقاتك اختفت. تنظر إلى سلسلة أخطاء لم تكن موجودة من قبل، وحيثما يجمع سجل التغييرات رطوبة.

هذا قصة من نظام Semver. بشكل خاص، هذا خطأ منك.

ما يعنيه الثلاثة أرقام فعليًا

MAJOR.MINOR.PATCH — هذا كل شيء. ثلاث مساحات، ثلاث قواعد:

PATCH (1.2.3 → 1.2.4): تصحيح عطل. لا حاجة لتعديل أي جزء من كودك. فقط تصبح سلوكك أقل تلفًا.
MINOR (1.2.3 → 1.3.0): تم إضافة ميزة جديدة، وتم التأكد من توافقها مع الأقدم. لا يجب أن تستخدمها، لكنها موجودة.
MAJOR (1.2.3 → 2.0.0): شيء فشل. تم تغيير اسم دالة أو إزالتها أو تغيير توقيعها. تم إزالة الواجهة القديمة أو أصبحت تعمل بشكل مختلف.

الكلمة المهمة في الثلاثة هي متوافق مع الواجهة القديمة. MINOR وPATCH هي التزامات: "لم نُدمِر أي شيء كنت تستخدمه بالفعل". MAJOR هي تحذير: "لقد فعلنا ذلك".

عندما يرفع المُحافظ رقم MAJOR وتم تجاهله لأنك قمت بربطه ^1.0.0 في package.json وتم تجاهله في ملف التثبيت القديم — هذا على عاتقك. كان المعيار يعمل بالضبط كما طُوّر.

الاتفاق الاجتماعي حول Semver

Semver هو اتفاق تقليدي، وليس قانونًا. يمكن للبرامج أن تدّعي الالتزام به ثم تُصدر إصدارًا MINOR يحتوي على تغييرات مُسلطة. عندما يحدث ذلك، فإن ذلك يُعدّ انتهاكًا من قبل المُحافظ. ولكن عندما يُرفع الإصدار MAJOR بشكل صحيح ليعبر عن التغييرات المُسلطة، وتم تثبيته بشكل مُباشر — فإنك من أنت الذي أدى إلى تدمير بنية تطبيتك.

هذا هو السبب في وجود سجل التغييرات. مدخل ينص على "تم إزالة الميزة المُستبعدة CHANGELOG.md — استخدم v1Api بدلاً من ذلك" v2Api هو ما يُظهره المُحافظ في جانب الالتزام. عدم قراءة هذا هو ما يُظهر أنك تتجاهله. السجل يُقرأ في دقيقتين. الجلسة التصحيحية التي يمنعها لا تُعدّ مُستحيلة.

^ مقابل ~ — الميكانيكية الفعلية

في package.json, ^ (caret) و ~ (tilde) يحددان مساحة الإصدارات. يشبهان بعضهما البعض ويُظهران سلوكًا مختلفًا تمامًا.

Caret (^): يسمح بأي إصدار لا يرفع رقم MAJOR. هذا هو الافتراض الافتراضي لـ npm عندما تُستخدم npm install some-package.

^1.2.3 تُحلّل إلى >=1.2.3 <2.0.0
^0.2.3 تُحلّل إلى >=0.2.3 <0.3.0 — حالة خاصة: 0.x تُعامل MINOR كمُسلطة
^0.0.3 تُحلّل إلى >=0.0.3 <0.0.4 — 0.0.x تُثبّت بدقة، بدون مرونة

Tilde (~): يسمح فقط بتحديثات PATCH، ضمن الإصدار المحدد للMINOR.

~1.2.3 تُحلّل إلى >=1.2.3 <1.3.0
~1.2 تُحلّل إلى >=1.2.0 <1.3.0 — نفس ما يُعرف بـ ~1.2.0
~1 تُحلّل إلى >=1.0.0 <2.0.0 — مكافئ لـ ^1.0.0 في هذه المرحلة

أمثلة على مساحة الإصدار

يتراوح	ما يسمح به	مطابقة محددة
`1.2.3`	الإصدار المحدد	فقط 1.2.3
`^1.2.3`	أي إصدار MINOR أو PATCH ≥ 1.2.3	1.2.4، 1.3.0، 1.99.0 — ليس 2.0.0
`^0.2.3`	تحديثات PATCH فقط داخل 0.2.x	0.2.4، 0.2.99 — ليس 0.3.0
`~1.2.3`	تحديثات PATCH فقط داخل 1.2.x	1.2.4، 1.2.99 — ليس 1.3.0
`~1.2`	أي تحديث للـ 1.2.x	1.2.0, 1.2.1, 1.2.99
`>=1.2.3 <2.0.0`	مجال محدد	نفس النتيجة كـ ^1.2.3
`1.2.x`	أي تحديث للـ 1.2	1.2.0, 1.2.1, 1.2.99
`*`	أي شيء ممكن	أي شيء يشعر به npm في اليوم الحالي

ال * مجال الإصدار هو استراتيجية "أنا أثق بك". لا تُثبّت أي شيء. إذا أصدرت مكتبة إصدارًا مُعاد بناءً على واجهة جديدة، فستحصل عليه في التثبيت التالي v9.0.0 بمُستودع نظيف. استخدمه فقط في التطبيقات الرئيسية التي لا تُعتمد عليها من قبل مكتبات أخرى — وحتى في هذه الحالة، فقط إذا لم يكن التكرار مهمًا حقًا (وهو كذلك). npm install بمُحَوَّلٍ نظيف. استخدمه فقط في التطبيقات الأساسية التي لا تُعتمد عليها من قبل مُعالِجات أخرى — وحتى في هذه الحالة، فقط إذا لم يكن التكرار المُهم في تجربتك (وهو مُهم).

مُحددات الإصدار المبكر

قبل الإصدار المستقر، يُستخدم المُحافظ تسمية مبكرة للإصدار:

1.0.0-alpha.1 — مبكر، غير مستقر، الواجهة قد تُغيّر
1.0.0-beta.2 — مكتمل الوظائف، يُختبر، توقع بعض العيوب
1.0.0-rc.1 — مُعدّ للإطلاق، يمكن استخدامه في الإنتاج ما لم يظهر شيء في الاختبار النهائي

الإصدارات المبكرة تُرتّب أقل من الإصدار المستقر: 1.0.0-alpha.1 < 1.0.0. وبشكل حاسم، ^1.0.0 سيتم تثبيت لا — تُوافق فقط إذا أُدخلت بشكل مُحدد في مساحة التثبيت. هذا السلوك هو ما يمنعك من اختيار إصدار مبكر عشوائيًا عندما كنت ترغب في تتبع الإصدارات المستقرة. 2.0.0-beta.1 — تُطابق الإصدارات المُسبقة فقط إذا وضعتها بشكل صريح في نطاقك. وهذا السلوك هو الذي يمنعك من اختيار إصدار ألفا بشكل عفوي عندما كنت تقصد تتبع إصدارات مستقرة.

إذا كنت تستخدم مكتبة لا تمتلك إصدارات مستقرة، فقم بربط سلسلة الإصدار الكاملة: "some-package": "1.0.0-beta.2". لا تستخدم ^ أو ~ مع الإصدارات المبكرة إلا إذا كنت تعرف أن المُحافظ يتعامل معها بحذر — معظمهم لا يفعلون ذلك.

التحقق من المدى قبل التثبيت

قبل التثبيت على مساحة الإصدار في package.json، من المهم التأكد من ما الذي تتفق عليه للاستثمار. المُحسّن لـ Semver يأخذ مساحة الإصدار وقائمة من الإصدارات المُمكنة ويعرض لك أي منها يتطابق — مفيد عند عدم معرفتك ما إذا كانت تغطي الإصدار المطلوب، أو عند مراجعة طلب تغيير وتشعر أن المدى غير منطقي. الثلاثة أنماط الفشل ~2.3 أغلب فشل البناء المرتبط بـ Semver يتبع أحد الأشكال الثلاثة:

+ زيادة رقم MAJOR + حذف ملف التثبيت:

أنت قمت بربط

^ ، أصدر المُحافظ ، تم حذف الملف أو لم يُثبت، يُثبت CI الإصدار 2.0.0. الحل: قم بتوثيق ملف التثبيت. في كل المشروع. لا استثناءات. ^1.0.0في مكتبة تُصدرها: 2.0.0أنت مُطوّر مكتبة استخدمت
* لأحد الاعتماد. كل المستخدمين الذين يعتمدون على مكتبتك يورثون تثبيتك. لقد جعلت شبكة الاعتماد مشكلة لك. الحل: استخدم مساحات محددة في أي شيء تُرسله إلى npm. مُبكر بدون ملف تثبيت: * مجال مرن استلم
، تغير الواجهة من ، لا يعمل شيء. الحل: قم بربط الإصدارات المبكرة بشكل محدد و— قلها معني — قم بتوثيق ملف التثبيت. 1.0.0-alpha.3اقرأ السجل alpha.1عندما يُصدر أي إصدار من نوع MAJOR في أي مكون من شجرة الاعتماد، اقضِ دقيقتين على السجل. كتب المُحافظ ذلك حتى لا تضطر إلى تحليل التلف من سلسلة أخطاء في الساعة 3 صباحًا.

إذا أصدرت مكتبة تغييرات مُسلطة تحت ترقية MINOR دون سجل تغييرات — هذا يُعدّ انتهاكًا. ارفع طلبًا. اُعلن عنه علنًا. ولكن إذا كان الترقية MAJOR واضحة، وكان دليل التحول مفصلًا، وتم تثبيته دون مراجعة: فإن الأداة أجرت ما أخبرت بها. كان الالتزام مكتوبًا في الأرقام الثلاثة. فقط لم تقرأه.

When a MAJOR version ships for anything in your dependency tree, spend two minutes on the changelog. The maintainers wrote it so you wouldn’t have to reverse-engineer the breakage from a stack trace at 3am.

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