Semantische Versionsnummerierung Was die Zahlen in Ihrer package.json tatsächlich bedeuten

Jedes JavaScript-Projekt hat ein package.json. Die meisten Entwickler haben es bereits Hunderte Male eingegeben, ohne sich einmal um die Versionszeichen zu kümmern. Doch wenn man jemandem fragt, was npm install some-library tatsächlich erlaubt – also welche Versionen npm gerne zieht –, bekommt man oft nur eine Schulterzuckung. ^1.2.3 Das ist kein trivialer Lücke. Ein missverstandener Versionsbereich ist die Ursache dafür, dass eine Routine auf einem frischen System plötzlich einen CI-Pipeline, die für Monate funktioniert hat, bricht. Das Verständnis des Vertrags hinter diesen Zahlen ist eine der niedrig aufwendigen, hohen Rentabilität Dinge, die Entwickler unterscheiden, die Version-Problem in Minuten debuggen, von denen, die Stunden damit verbringen.

Das MAJOR.MINOR.PATCH-Vertrags npm install Semantische Versionierung (semver) ist ein dreistelliger Format:

. Jede Position trägt eine spezifische Versprechen über das, was sich geändert hat:

— Bruchänderungen. Eine Aktualisierung über eine Major-Version kann dazu führen, dass Sie Ihr Code aktualisieren müssen. MAJOR.MINOR.PATCH— Neue Funktionen, kompatibel. Ihr bestehender Code sollte weiterhin funktionieren.

• MAJOR — Bugfixes nur. Sicher zum Upgrade; keine API-Änderungen.
• MINOR Das ist das
• TEILEN Vertrags

die Pakete veröffentlichen. Ein Sprung von sollte neue Funktionen hinzufügen, ohne das bestehende Verhalten zu brechen. Ein Sprung zu ist Ihre Warnung: Lesen Sie die Changelog vor der Aktualisierung. 2.3.1 Zu 2.4.0 In der Praxis verlieren Wartungsteams manchmal ein Bruchverhalten in eine Minor-Veröffentlichung. Semver wird nicht automatisch erzwungen – es ist eine Konvention. Doch es gibt Ihnen ein Rahmenwerk, um Risiken zu bewerten, und es ist das, worauf alle Range-Operatoren basieren. 3.0.0 Was zählt als Bruchänderung?

Eine Bruchänderung ist alles, was die Nutzer zwingt, ihren Code zu aktualisieren:

Entfernung oder Umbenennung einer exportierten Funktion, Klasse oder Konstante

Änderung der Funktionssignatur – Entfernung von Parametern, Hinzufügen von erforderlichen Parametern oder Änderung der Rückgabewerte

• Änderung des beobachtbaren Verhaltens auf eine Weise, dass korrekte Aufrufcode nun falsch verhält
• Änderung des Formatierungsstils einer Konfigurationsdatei auf eine inkompatible Weise
• Hinzufügen eines neuen optionalen Parameters? Das ist MINOR. Hinzufügen einer neuen Export? MINOR. Behebung eines Bugs, den jemand versehentlich als Funktion nutzt? Das ist eine Entscheidung, aber konventionell PATCH. Wenn unsicher, erhöhen Sie MINOR und dokumentieren Sie es klar.
• Versionsbereichs-Operatoren in package.json

Öffnen Sie jedes

und Sie sehen Versionen wie

. Diese sind keine genauen Pins – sie sind package.json Bereiche "^4.17.21" oder "~1.0.4"die npm oder yarn sagen, welche Versionen akzeptabel sind, wenn Ihr Abhängigkeitsbaum berechnet wird. Caret ^ – Kompatibel mit Version Der Caret ist der Standardoperator, wenn Sie

ausführen. Es bedeutet: „Akzeptiere jede Version, die die linke nicht-null-Ziffer nicht ändert.“ In der Praxis bedeutet das für stabile Pakete: gleiche Major, beliebige Minor oder Patch:

Das Verhalten mit Null-Major ist absichtlich. Pakete mit npm installsignalisieren „unstable API“ – jede Minor-Version könnte Dinge brechen. Der Caret respektiert dieses Signal und wird viel konservernder.

^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)

Tilde ~ – Nur Patch-Ebene-Updates 0.x.x Die Tilde ist konservernder. Sie akzeptiert neue Patches, aber berührt die Minor-Version nicht:

Greifen Sie auf

zu, wenn Sie Bugfixes benötigen, aber sich unsicher sind, ob das Paket semver für Minor-Updates respektiert, oder wenn Ihr Code eng an eine bestimmte API-Oberfläche gekoppelt ist und eine neue Funktion in der Vergangenheit oft feine Verhaltensänderungen mit sich bringt.

~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)

Vergleichsoperatoren: >=, ~ Sie können beliebige Bereiche mit Vergleichsoperatoren schreiben. Ein Leerzeichen zwischen zwei Bedingungen bedeutet AND:

Diese kommen am häufigsten in <=, >

vor, wo ein Paket etwas wie

>=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

deklariert, welche Host-Versionen es kompatibel ist. peerDependenciesWildcards: * und x "react": ">=16.8.0 <19.0.0" Die Wildcard-Formen sind hauptsächlich für die Lesbarkeit der Dokumentation gedacht; npm behandelt sie als äquivalent zum Caret/Tilde mit einer Null-Basis:

— jede Version. Verwenden Sie dies nicht in der Produktion.

— jede 1.x.x (gleich wie

• * oder "" — jede 1.2.x (gleich wie
• 1.x oder 1.x.x Vorab-Versionen ^1.0.0)
• 1.2.x Vorab-Versionen sehen aus wie ~1.2.0)

. Sie werden als

niedriger 1.0.0-alpha.1, 2.0.0-beta.3, oder 3.1.0-rc.1als die Version mit den gleichen Zahlen betrachtet – Kritisch, bereichsoperatoren erlauben nicht automatisch Vorab-Versionen 1.0.0-alpha.1 < 1.0.0.

Ein Bereich wird nicht die Versionziehen, selbst wenn es technisch die Version ^1.0.0 erfüllt. Sie müssen explizit wählen: 1.1.0-beta.1Dies ist absichtliche Sicherheit. Sie würden selten wollen, dass ein CI automatisch eine >=1.0.0 <2.0.0Build eines Abhängigkeitspaketes wählt, weil es technisch eine Versionsbereich erfüllt. Wenn Sie Vorab-Versionen testen, tun Sie es absichtlich.

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

Lockfiles sind nicht optional -alpha Wenn npm Ihre

Bereich berechnet, wählt es die höchste kompatible Version, die zurzeit verfügbar ist

zu diesem Zeitpunkt ^1.2.3 heute und Sie erhalten . Führen Sie es sechs Monate später aus und Sie erhalten möglicherweise. Führen Sie aus npm install . Gleiche 1.5.0, unterschiedlicher Abhängigkeitsbaum, möglicherweise unterschiedliches Verhalten. 1.9.2Das ist, was Lockfiles lösen. package.json(npm) und

(yarn) erfassen die genaue Version, die für jeden Abhängigkeit installiert wurde – direkt und transitive. Wenn jemand anderes Ihr Repository klonen und package-lock.json ausführen, erhalten sie einen identischen Baum. yarn.lock Kommentieren Sie Ihr Lockfile. Immer. npm ciWenn es nicht kommentiert wird, dann:

Verschiedene Entwickler können unterschiedliche Abhängigkeitsversionen verwenden, ohne es zu wissen Ihre CI-Umgebung kann sich ohne Ihre Kenntnis von Ihrer lokalen Umgebung abweichen

• Eine aktualisierte transitive Abhängigkeit kann das Produktverhalten ändern, ohne dass sich Ihre
• offensichtlich ändert.
• Die Hauptaußerung: veröffentlichte Bibliotheken (nicht Anwendungen) konventionell lassen Lockfiles unkommentiert, damit die Verbraucher ihre eigenen Abhängigkeitsbaum lösen können. Wenn Sie eine Anwendung bauen, gibt es keinen guten Grund, das Lockfile aus dem Quellcode auszuschließen. git diff

"latest" in package.json ist immer ein Fehler

Manchmal sehen Sie dies in einem

Nicht tun. package.json:

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

kann auf die aktuell markierte Version "latest" auf npm – es ändert sich jedes Mal, wenn der Maintainer eine neue Version veröffentlicht. Ein neuer latest auf einem neuen Gerät könnte eine völlig andere Major-Version ziehen, die Sie getestet haben. npm install Es könnte für Wochen funktionieren, dann bricht es plötzlich, wenn das Paket eine neue Major veröffentlicht. Schlimmer noch, es macht

unbrauchbar als ein reproduzierbarer Spezifikation – Sie können nicht verstehen, welche Version Sie laufen, ohne npm manuell zu überprüfen. Pin auf eine echte Version und lassen Sie den Caret sicherere Updates innerhalb dieses Bereichs verarbeiten. package.json Prüfen Sie, ob eine Version einen Bereich erfüllt

Wenn Sie nicht sicher sind, ob eine Version einem gegebenen Bereich entspricht – besonders bei Null-Major-Paketen oder ungewöhnlichen komplexen Ausdrücken – gibt die

auf iotools.cloud Ihnen sofort eine Antwort. Geben Sie den Bereich ( Semver Version-Rechner & Bereich-Tester ) und die Kandidatenversion ein, und es sagt Ihnen, ob die Bedingung erfüllt ist.^1.2.3, ~0.5.0, >=2.0.0 <3.0.0Dies ist nützlich, wenn Sie Abhängigkeitsupgrade-PRs überprüfen, bei der Debugging, warum

zu einer unerwarteten Version gelangt ist, oder wenn Sie eine npm install Bereich vor der Veröffentlichung eines Pakets überprüfen. peerDependencies Operator

Schnellübersicht

Löst sich auf zu	Beispiel	1.2.0 oder höher, keine Obergrenze
^	^1.2.3	>=1.2.3 <2.0.0
~	~1.2.3	>=1.2.3 <1.3.0
>=	>=1.2.0	Jede Version (vermeiden)
*	*	Jede 1.2.x Patch
x	1.2.x	genau
genau 1.2.3	1.2.3	Semantische Versionierung: Was die Zahlen in Ihrem package.json tatsächlich bedeuten 2

Das könnte Ihnen auch gefallen