النسخة المعنوية ما تعني الأرقام في ملف package.json في الواقع

كل مشروع JavaScript يمتلك package.json. يكتب معظم المطورين npm install some-library مئات المرات دون أن يُفكر في سلسلة الإصدار. لكن إذا سألت شخصًا ما ما ^1.2.3 يسمح به — أي، أي إصدارات سيسمح npm بتنزيلها — فغالبًا سينتظر.

هذا ليس فجوة بسيطة. فهم سلسلة إصدار خاطئة هو السبب وراء توقف مُتكرر على جهاز جديد عن طريق توقف سلسلة تحقق (CI) التي كانت تعمل بشكل جيد لأشهر. npm install فهم العقد المُعتمد وراء هذه الأرقام هو أحد الأمور ذات التكلفة المنخفضة والنتيجة العالية التي تُفصل بين المطورين الذين يحلون مشكلات الإصدارات في دقائق وبين من يقضون ساعات في ذلك.

عقد MAJOR.MINOR.PATCH

الإصدار المعنوي (semver) هو صيغة مكونة من رقمين: MAJOR.MINOR.PATCH. كل موضع يحمل تزامنًا مع التغييرات المحددة:

• MAJOR — تغييرات تُحدث تغييرات في الأداء. قد يتطلب ترقية إلى إصدار رئيسي أن تُحدث تغييرات في كودك.
• MINOR — ميزات جديدة، متوافقة مع الاتجاهات السابقة. يجب أن يظل كودك الحالي يعمل.
• PATCH — تصحيحات أخطاء فقط. يمكن الترقية بسهولة؛ لا توجد تغييرات في واجهة البرمجة.

هذا هو العهد الذي يُنشر تحته مُتطلبات الأدوات. الانتقال من 2.3.1 ل 2.4.0 يجب أن يضيف ميزات جديدة دون أن يُحدث تغييرات في السلوك الحالي. الانتقال إلى 3.0.0 هو إشارة تحذيرية: اقرأ سجل التغييرات قبل الترقية.

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

ما الذي يُعد تغييرًا مُسببًا للإغلاق؟

أي شيء يُجبر المستهلكين على تحديث كودهم:

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

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

مُشغلات النطاق في package.json

افتح أي package.json وسترى سلاسل إصدارات مثل "^4.17.21" أو "~1.0.4". هذه ليست نقاط دقيق — هي نطاقات تُخبر npm أو yarn أي إصدارات مقبولة عند تحليل شجرة الاعتماد.

الرمز-caret ^ — متوافق مع الإصدار

الرمز-caret هو المُشغل الافتراضي عندما تُجرى npm install. يعني: "أقبل أي إصدار لا يُغيّر الرقم غير الصفر الأيسر". في الممارسة، بالنسبة للإصدارات المستقرة، هذا يعني نفس الإصدار الرئيسي، أي إصدار فرعي أو ترقية:

^1.2.3  →  >=1.2.3 <2.0.0   (any 1.x.x at or above 1.2.3)
^0.2.3  →  >=0.2.3 <0.3.0   (zero-major: pins to minor)
^0.0.3  →  >=0.0.3 <0.0.4   (zero-zero: pins to exact patch)

السلوك عند الإصدار الصفر للرئيسي هو مقصود. الإصدارات عند 0.x.x تُشير إلى "واجهة غير مستقرة" — أي إصدار فرعي قد يُحدث تغييرات. يُحترم هذا الإشارة ويصبح أكثر تواضعًا.

الرمز-tilde ~ — ترقية على مستوى الترقية فقط

الرمز-tilde أكثر تواضعًا. يقبل الترقية على التصحيحات فقط ولا يُغير الإصدار الفرعي:

~1.2.3  →  >=1.2.3 <1.3.0   (any 1.2.x at or above 1.2.3)
~1.2    →  >=1.2.0 <1.3.0
~1      →  >=1.0.0 <2.0.0   (when only major given — same as ^1)

استخدم ~ عندما ترغب في ترقية الأخطاء ولكنك غير متأكد أن المكتبة تُحترم Semver في الترقية الفرعية، أو عندما يكون كودك مرتبطًا بشكل وثيق بواجهة معينة، وترقية الميزات تأتي مع تغييرات خفيفة في السلوك.

مُشغلات المقارنة: >=, <=, >

يمكنك كتابة نطاقات مُحددة باستخدام مُشغلات المقارنة. الفراغ بين مُحددتين يعني "و":

>=1.2.0           # at least 1.2.0, no upper bound
>=1.2.0 <2.0.0   # same as ^1.2.0 (explicit AND)
>1.2.0 <=1.5.0   # between these values, exclusive/inclusive

تظهر هذه أكثر في peerDependenciesحيث تقول مكتبة ما شيء مثل "react": ">=16.8.0 <19.0.0" لإظهار أي إصدارات من المضيف تتوافق معها.

الرموز: * وx

الرموز المُتعددة تُستخدم بشكل رئيسي لتحسين قابلية القراءة؛ يتعامل npm معها كمُتعددة مماثلة للرمز-caret أو الـtilde مع أساس صفر:

• * أو "" — أي إصدار. لا تستخدم هذا في الإصدارات الإنتاجية.
• 1.x أو 1.x.x — أي 1.x.x (مطابق لـ ^1.0.0)
• 1.2.x — أي 1.2.x (مطابق لـ ~1.2.0)

الإصدارات المُسبقة

تبدو مثل 1.0.0-alpha.1, 2.0.0-beta.3، أو 3.1.0-rc.1. تُعتبر أقل من الإصدار المُعلن بذات الأرقام — 1.0.0-alpha.1 < 1.0.0.

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

npm install some-library@next
npm install some-library@2.0.0-beta.3

ملفات التثبيت ليست اختيارية -alpha عندما يحلل npm إصدارك

نطاق، فإنه يختار الإصدار الأعلى الممكن المتاح

في تلك اللحظة ^1.2.3 إذا أجريت اليوم، فستحصل على إذا أجريت بعد ستة أشهر، فقد تحصل علىنفس npm install شجرة اعتماد مختلفة، سلوك مختلف. 1.5.0هذا ما يحله ملفات التثبيت. 1.9.2(npm) و package.json(yarn) تُسجل الإصدار الدقيق المُثبت لكل اعتماد — مباشر ومتسلسل. عندما يُنسخ مُطور آخر مُخزنك ويُجرِّي

فسيحصل على شجرة متماثلة. package-lock.json أدرج ملف التثبيت. دائمًا. yarn.lock عدم أخذ ملف التثبيت يعني: npm ciقد يُستخدم مطوران إصدارات مختلفة من الاعتماد دون أن يعلموا ذلك

بيئة CI قد تُختلف تلقائيًا عن بيئة المُطور المحلي تحديث في اعتماد متسلسل قد يُغيّر سلوك الإنتاج بدون تغيير مرئي في

• الاستثناء الرئيسي: المكتبات المُنشورة (وليس التطبيقات) تُترك ملفات التثبيت غير المُسجلة بحيث يمكن للمستهلكين تحليل شجرة الاعتماد الخاصة بهم. إذا كنت تُطور تطبيقًا، فلا يوجد سبب جيد لترك ملف التثبيت خارج التحكم المُستند.
• "الأخير" في package.json هو خطأ دائمًا
• أحيانًا ترى هذا في git diff

لا تفعل ذلك.

يُشير إلى أي إصدار مُلصق حاليًا

على npm — يُغيّر كلما نشر المُحافظ إصدارًا جديدًا. قد يُسحب على جهاز جديد إصدار رئيسي مختلف عن الذي تم اختباره عليه. package.json:

"dependencies": {
  "some-package": "latest"
}

قد يعمل بشكل جيد لأسابيع، ثم يُوقف تلقائيًا عندما يُنشر إصدار رئيسي جديد. أسوأ ما يحصل عليه هو أن يجعل "latest" غير مفيد كمُعيار قابل للإعادة — لا يمكنك التفكير في أي إصدار تعمل عليه بدون التحقق يدويًا من npm. اربط إلى إصدار حقيقي ودع الرمز-caret يُدير الترقية الآمنة داخل هذا النطاق. latest تحقق مما إذا كان الإصدار يُحقق النطاق npm install إذا كنت غير متأكد مما إذا كان الإصدار يُحقق النطاق المُحدد — خاصة مع الإصدارات ذات الصفر في الرئيسي أو التعبيرات غير المعتادة — فإن

على iotools.cloud يُعطي إجابة فورية. أدخل النطاق ( package.json ) والنسخة المُطروحة، ويساعدك على معرفة ما إذا كان القيود مُحققة.

هذا مفيد عند مراجعة طلبات ترقية الاعتماد، أو تحليل سبب

تم تحليله إلى إصدار غير متوقع، أو التحقق من نطاق محاسبة إصدار SemVer واختبار النطاق قبل نشر مكتبة.^1.2.3, ~0.5.0, >=2.0.0 <3.0.0مُشغل

يُحل إلى npm install 1.2.0 أو أعلى، بدون حد peerDependencies أي إصدار (تجنب)

الرجوع السريع

أي 1.2.x ترقية	مثال	مُحدد
^	^1.2.3	>=1.2.3 <2.0.0
~	~1.2.3	>=1.2.3 <1.3.0
>=	>=1.2.0	بالضبط 1.2.3
*	*	أي نسخة (تجنبها)
x	1.2.x	أي إصدار 1.2.x
دقيقة	1.2.3	دقيقة 1.2.3

قد يعجبك أيضاً