Semantische Versionsnummerierung Die Nummerierungssystem, auf das Ihr npm-Install abhängt

Ihre Build hat versagt. Funktioniert am Freitag. npm install am Montag wurde eingezogen react-query@5 und jetzt sind die Hälfte Ihrer Hooks verschwunden. Sie starren auf eine Stacktrace, die zuvor nicht da war, und irgendwo sammelt sich eine Changelog in Staub.

Dies ist eine semver-Geschichte. Speziell, das liegt an Ihnen.

Was die drei Zahlen tatsächlich bedeuten

MAJOR.MINOR.PATCH — das ist es. Drei Felder, drei Regeln:

• TEILEN (1.2.3 → 1.2.4): Bugbehebung. Nichts in Ihrem Code muss geändert werden. Sie erhalten einfach weniger fehlerhafte Verhalten.
• MINOR (1.2.3 → 1.3.0): Eine neue Funktion wurde hinzugefügt, ist backward-compatible. Sie müssen sie nicht verwenden, aber sie ist vorhanden.
• MAJOR (1.2.3 → 2.0.0): Etwas ist kaputt gegangen. Eine Funktion wurde umbenannt, entfernt oder die Signatur geändert. Die alte API ist verschwunden oder funktioniert anders.

Das Schlüsselwort in allen drei ist backward-compatible. MINOR und PATCH sind Versprechen: „Wir haben nichts an dem gebrochen, was Sie bereits verwenden.“ MAJOR ist eine Warnung: „Wir haben es getan.“

Wenn ein Maintainer einen MAJOR-Bump macht und Sie es nicht bemerken, weil Sie in package.json gepinnt haben und das Lockfile veraltet war — das liegt an Ihnen. Das Spezifikationsverhalten funktionierte genau wie geplant. ^1.0.0 Der semver-soziale Vertrag

Semver ist eine Konvention, keine Gesetzgebung. Pakete können behaupten, es zu befolgen, und dann eine MINOR-Version mit brüchigen Änderungen veröffentlichen. Wenn das passiert, ist das eine schlechte Absicht des Maintainer. Aber wenn ein Paket korrekt einen MAJOR-Bump macht, um Bruch zu signalisieren, und Sie es blind ziehen — dann sind Sie derjenige, der Ihr eigenes Build gebrochen hat.

Das ist der Grund, warum Changelogs existieren. Ein Eintrag, der sagt „Entfernt abgelegene

— verwenden CHANGELOG.md anstatt“ ist die Verpflichtung des Maintainer. Nichts zu lesen ist Ihre Verpflichtung. Das Changelog ist eine zwei-minütige Lektüre. Die Debugging-Sitzung, die es verhindert, ist nicht. v1Api ^ vs ~ — die tatsächlichen Mechanismen v2Api (Caret) und

(Tilde) definieren Versionsbereiche. Sie sehen ähnlich aus und verhalten sich sehr unterschiedlich.

In package.json, ^ Caret (^): ~ Erlaubt alles, was den MAJOR nicht erhöht. Dies ist das Standardverhalten von npm, wenn Sie

ausführen. resolves to npm install some-package.

• ^1.2.3 — Sonderfall: >=1.2.3 <2.0.0
• ^0.2.3 — Sonderfall: >=0.2.3 <0.3.0 behandelt MINOR als brüchig 0.x pins genau, ohne Spielraum
• ^0.0.3 — Sonderfall: >=0.0.3 <0.0.4 — 0.0.x Tilde (~):

Erlaubt nur PATCH-Updates innerhalb des spezifizierten MINOR. — gleich wie

• ~1.2.3 — Sonderfall: >=1.2.3 <1.3.0
• ~1.2 — Sonderfall: >=1.2.0 <1.3.0 — äquivalent zu ~1.2.0
• ~1 — Sonderfall: >=1.0.0 <2.0.0 in diesem Punkt ^1.0.0 Versionsbereichsbeispiele

Was es erlaubt

Der * mit einem sauberen Cache. Verwenden Sie es nur in obersten Anwendungen, die nicht von anderen Paketen abhängen — und selbst dann nur, wenn Wiederholbarkeit tatsächlich nicht wichtig ist (es ist). v9.0.0 Vorab-Identifikatoren npm install Bevor eine stabile Version veröffentlicht wird, taggen die Maintainer Versionen mit einem Vorab-Label:

— frühe, instabile, die API ändert sich wahrscheinlich noch

— vollständig mit Funktionen, wird noch getestet, erwarten Sie einige unvollkommene Elemente

• 1.0.0-alpha.1 — Release-Kandidat, sollte für Produktion bereit sein, es sei denn, etwas tritt in der Endprüfung auf
• 1.0.0-beta.2 Vorab-Versionen werden
• 1.0.0-rc.1 unterhalb

der stabilen Version sortiert: Und kritisch, installiert 1.0.0-alpha.1 < 1.0.0— Vorab-Versionen werden nur dann installiert, wenn Sie sie explizit in Ihrem Bereich angeben. Dieses Verhalten verhindert, dass Sie versehentlich eine Alpha-Version wählen, wenn Sie stattdessen stabile Versionen verfolgen wollten. ^1.0.0 Wenn Sie ein Paket konsumieren, das nur Vorab-Versionen hat, pinnen Sie die vollständige Version: nicht . Verwenden Sie 2.0.0-beta.1 nicht mit Vorab-Versionen, es sei denn, Sie wissen, dass der Maintainer sie sorgfältig behandelt — die meisten nicht.

Prüfen eines Bereichs vor dem Commit "some-package": "1.0.0-beta.2"Bevor Sie eine Versionsspezifikation in ^ oder ~ pinnen, lohnt es sich, zu überprüfen, was Sie tatsächlich installieren. Der

Semver Version Calculator

nimmt eine Versionsspezifikation und eine Liste an Kandidatenversionen und zeigt Ihnen, welche davon übereinstimmen — nützlich, wenn Sie unsicher sind, ob package.jsoneine bestimmte Version abdeckt, oder wenn Sie einen PR überprüfen und der Bereich falsch aussieht. Die drei Fehlermodi Die meisten semver-verwandten Build-Fehler folgen einem der drei Muster: ~2.3 + MAJOR-Bump + gelöschter Lockfile:

Sie haben

gepinnt, der Maintainer hat

1. ^ veröffentlicht, das Lockfile wurde gelöscht oder nie commitiert, CI installiert 2.0.0. Fix: Commit Ihr Lockfile. Jedes Projekt. Keine Ausnahmen. in einer Bibliothek, die Sie veröffentlichen: ^1.0.0Sie sind ein Bibliotheksaussteller, der für eine Abhängigkeit 2.0.0verwendet hat. Jeder Abhängigkeitsgraph der untergeordneten Benutzer erbt Ihr Wildcard. Sie haben ihre Abhängigkeitsstruktur zu Ihrem Problem gemacht. Fix: Verwenden Sie explizite Versionen in alles, was Sie an npm veröffentlichen.
2. * Vorabversion ohne Lockfile: Ein lockerer Bereich hat * eingezogen, die API wurde von
3. geändert, nichts funktioniert. Fix: Pinnen Sie Vorabversionen explizit und — sagen Sie es mit mir — commiten Sie das Lockfile. Lesen Sie die Changelog 1.0.0-alpha.3Wenn eine MAJOR-Version für irgendetwas in Ihrem Abhängigkeitsbaum veröffentlicht wird, verbringen Sie zwei Minuten mit der Changelog. Die Maintainer haben es geschrieben, damit Sie nicht aus einem Stacktrace um 3 Uhr morgens rückwärts schließen müssen. alpha.1Wenn ein Paket unter einer MINOR-Bump brüchige Änderungen veröffentlicht, ohne Changelog — das ist schlechte Absicht. Stellen Sie ein Issue ein. Nennen Sie es öffentlich. Aber wenn die MAJOR klar war, die Migrationsanleitung detailliert war und Sie es ohne Blick darauf gezogen haben: das Tooling hat genau das getan, was Sie ihm gesagt haben. Der Vertrag wurde in drei Zahlen geschrieben. Sie haben ihn einfach nicht gelesen.

Semantische Versionsnummerierung: Die Nummerierungssystem, auf das Ihr npm install abhängt 2

Semantische Versionsnummerierung: Die Nummerierungssystem, auf das Ihr npm install abhängt 1

Wenn eine Bibliothek unter einer MINOR-Aufstockung brüchige Änderungen veröffentlicht und dabei keine Changelog enthält – das ist schlechte Absicht. Erstelle ein Issue. Nenne es öffentlich. Aber wenn die MAJOR-Aufstockung offensichtlich vorhanden war, die Migrationsanleitung detailliert war und du sie ohne genau hinzusehen eingezogen hast: das Tooling hat genau das getan, was du ihm gesagt hast. Der Vertrag wurde in drei Zahlen formuliert. Du hast ihn einfach nicht gelesen.

Das könnte Ihnen auch gefallen

Neu

Managing .env Files Without Leaking Your Secrets

Mehr lesen "

Aktualisiert am Juni 27, 2026

Neu

Feature Flags Done Right — Three Patterns That Don't End in a 200-Line if Chain

Mehr lesen "

Aktualisiert am Juni 27, 2026

Neu

gRPC and Protocol Buffers: What Your .proto Files Actually Compile To

Mehr lesen "

Aktualisiert am Juni 26, 2026

Neu

CORS erklärt: Why Your API Keeps Blocking You (and How to Fix It)

Mehr lesen "

Aktualisiert am Juni 26, 2026