Semantic Versioning erklärt

May 10, 2026 · 4 min read

Wenn Sie schon einmal eine package.json-Datei geöffnet und sich gefragt haben, warum eine Abhängigkeit mit ^1.4.2 und eine andere mit ~2.0.1 angegeben ist, haben Sie es bereits mit den praktischen Konsequenzen von Semantic Versioning zu tun. Das Verständnis der Funktionsweise von SemVer hilft Ihnen, bessere Entscheidungen über Abhängigkeitsaktualisierungen zu treffen, fehlerhafte Builds zu vermeiden und Änderungen klar zu kommunizieren, wenn Sie selbst Pakete veröffentlichen.

Wichtige Erkenntnisse

SemVer verwendet ein MAJOR.MINOR.PATCH-Format, wobei jedes Segment eine bestimmte Art von Änderung signalisiert: Breaking Changes, Erweiterungen oder Korrekturen.
npm-Bereichsoperatoren (^, ~ und exakte Versionen) steuern, wie Abhängigkeiten aktualisiert werden, wobei das Caret-Zeichen der Standard und innerhalb einer Major-Version am freizügigsten ist.
Lock-Dateien wie package-lock.json sorgen für reproduzierbare Installationen über Teams und CI-Umgebungen hinweg, unabhängig vom angegebenen Bereich.
Versionen unter 1.0.0 gelten als instabil, und Pre-Release-Tags (z. B. 1.0.0-beta.1) werden als explizit instabile Releases behandelt, die npm nicht über normale Bereiche installiert, sofern dies nicht ausdrücklich angefordert wird.
SemVer ist ein sozialer Vertrag zwischen Maintainern und Konsumenten, kein technischer Durchsetzungsmechanismus.

Was ist Semantic Versioning?

Semantic Versioning (SemVer) ist eine Versionierungsspezifikation, die Versionsnummern eine Bedeutung zuweist. Eine SemVer-Version hat das Format MAJOR.MINOR.PATCH, wobei jede Zahl eine bestimmte Art von Änderung signalisiert:

MAJOR — eine Breaking Change, die mit der vorherigen öffentlichen API inkompatibel ist
MINOR — neue Funktionalität, die abwärtskompatibel hinzugefügt wurde
PATCH — eine abwärtskompatible Fehlerbehebung

Wenn ein Paket von 2.6.9 auf 3.0.0 wechselt, wurde die Abwärtskompatibilität gebrochen. Ein Wechsel von 2.6.9 auf 2.7.0 fügt Funktionen hinzu, ohne etwas zu brechen. Ein Wechsel auf 2.6.10 behebt einen Fehler.

Eine wichtige Klarstellung: SemVer funktioniert nur dann sinnvoll, wenn ein Paket eine definierte öffentliche API besitzt. Ohne einen klaren Vertrag zwischen dem Paket und seinen Konsumenten ist die Versionsnummer nur eine Zahl.

Wie npm SemVer für Abhängigkeitsbereiche verwendet

Die npm-Versionierung baut direkt auf SemVer auf, aber die Bereichssyntax in package.json ist eine Schicht darüber – nicht SemVer selbst.

"dependencies": {
  "lodash": "^4.17.21",
  "axios": "~1.6.0",
  "react": "18.2.0"
}

Folgendes bedeuten die einzelnen Bereichsoperatoren:

^ (Caret) — erlaubt MINOR- und PATCH-Updates, aber keine MAJOR-Updates. ^4.17.21 akzeptiert alles von 4.17.21 bis ausschließlich 5.0.0. Für 0.x-Releases sind Caret-Bereiche restriktiver: ^0.2.3 erlaubt Updates unterhalb von 0.3.0, nicht alle 0.x-Versionen.
~ (Tilde) — erlaubt PATCH-Updates, wenn eine Minor-Version angegeben ist. ~1.6.0 akzeptiert 1.6.x, aber nicht 1.7.0.
Exakte Version — 18.2.0 installiert nur diese spezifische Version.

Das Caret ist der Standard von npm, wenn Sie npm install ausführen. Es liefert Ihnen automatisch Fehlerbehebungen und neue Funktionen und schützt Sie gleichzeitig vor Breaking Changes – vorausgesetzt, der Paketautor befolgt SemVer korrekt. Diese Annahme trifft nicht immer zu.

Warum Lock-Dateien wichtig sind

Ihre package-lock.json zeichnet die zu einem bestimmten Zeitpunkt installierte exakte Version auf. Selbst wenn ein Bereich wie ^4.17.21 neuere Versionen zulässt, fixiert die Lock-Datei, was tatsächlich in Ihrem Team und in der CI-Umgebung verwendet wird. Deshalb ist es für reproduzierbare Builds wichtig, Ihre Lock-Datei zu committen.

0.x-Releases und Pre-Release-Versionen verstehen

Zwei Bereiche überraschen Entwickler häufig:

0.x-Releases sind per Definition instabil. Ein Paket bei 0.4.2 macht keine Kompatibilitätszusagen. Zwischen 0.4.2 und 0.5.0 kann sich alles ändern. Verlassen Sie sich nicht auf die Kompatibilitätsregeln von SemVer für Pakete, die noch nicht 1.0.0 erreicht haben.

Pre-Release-Versionen wie 1.0.0-beta.1 haben eine niedrigere Priorität als das stabile Release. npm installiert eine Pre-Release-Version nicht, es sei denn, Sie fordern dies explizit an. Ein normaler Bereich wie ^1.0.0 wird nicht automatisch zu 1.1.0-beta.1 aufgelöst. Das schützt Sie davor, versehentlich instabilen Code einzubinden.

Wann welche Version erhöht werden sollte

Wenn Sie ein Paket pflegen, verwenden Sie dies als Leitfaden:

Änderungsart	Zu erhöhende Version	Beispiel
Breaking API-Änderung	MAJOR	`1.4.2` → `2.0.0`
Neue Funktion, abwärtskompatibel	MINOR	`1.4.2` → `1.5.0`
Nur Fehlerbehebung	PATCH	`1.4.2` → `1.4.3`
Veraltung einer Funktion (ohne Entfernung)	MINOR	`1.4.2` → `1.5.0`

Wenn Sie MINOR erhöhen, setzen Sie PATCH auf null zurück. Wenn Sie MAJOR erhöhen, setzen Sie sowohl MINOR als auch PATCH auf null zurück.

SemVer ist ein Vertrag, keine Garantie

SemVer bietet Ihnen eine gemeinsame Sprache zur Kommunikation von Änderungen. Aber technisch hindert es einen Maintainer nicht daran, eine Breaking Change in einem Patch-Release auszuliefern. Tools wie semantic-release können die Versionierung anhand von Commit-Nachrichten automatisieren, manuelle Fehler reduzieren und Teams dabei helfen, SemVer-Konventionen konsistenter einzuhalten.

Fazit

Wenn Sie npm-Versionierung und Paketversionierung durch die Linse von SemVer betrachten, werden Sie zu einem selbstbewussteren Konsumenten von Open-Source-Paketen – und zu einem verantwortungsvolleren Veröffentlicher Ihrer eigenen Pakete. Das Format ist einfach, aber seine Implikationen reichen tief: Jede Ziffer kommuniziert Absicht, jeder Bereichsoperator gestaltet Risiko, und jede Lock-Datei sichert Reproduzierbarkeit. Behandeln Sie SemVer als das gemeinsame Vokabular, als das es konzipiert wurde, und Ihr Abhängigkeitsmanagement wird spürbar entspannter.

FAQs

Sie können Breaking Changes über das erhalten, was eigentlich ein sicheres Update sein sollte, etwa ein Patch- oder Minor-Bump. Um sich zu schützen, committen Sie Ihre package-lock.json, prüfen Sie Changelogs vor dem Upgrade und ziehen Sie Tools wie Renovate oder Dependabot in Betracht, die Release Notes zusammen mit Versionserhöhungen anzeigen. Für kritische Abhängigkeiten ist das Festschreiben exakter Versionen eine sinnvolle Schutzmaßnahme.

Caret ist der npm-Standard und funktioniert für die meisten Anwendungen gut, da es Minor- und Patch-Updates innerhalb einer Major-Version erlaubt. Tilde ist strenger und akzeptiert nur Patch-Updates, was für Projekte geeignet ist, die Stabilität über neue Funktionen stellen. Für Bibliotheken, die Sie veröffentlichen, sollten Sie Caret-Bereiche bevorzugen, damit Konsumenten automatisch von abwärtskompatiblen Verbesserungen profitieren.

Die SemVer-Spezifikation besagt ausdrücklich, dass alles unter 1.0.0 als anfängliche Entwicklung gilt, bei der die öffentliche API nicht als stabil betrachtet werden sollte. Maintainer können zwischen beliebigen 0.x-Releases Breaking Changes einführen, ohne die Major-Nummer zu erhöhen. Sobald ein Projekt 1.0.0 erreicht, verpflichtet es sich zu den vollständigen SemVer-Kompatibilitätsregeln.

Sie müssen sie explizit anfordern, entweder durch Angabe der exakten Version (npm install package@1.0.0-beta.1) oder durch Verwendung eines Tags (npm install package@next). Standardbereiche wie ^1.0.0 überspringen Pre-Release-Versionen vollständig, was die versehentliche Installation instabilen Codes in Produktionsumgebungen verhindert.

Gain control over your UX

See how users are using your site as if you were sitting next to them, learn and iterate faster with OpenReplay. — the open-source session replay tool for developers. Self-host it in minutes, and have complete control over your customer data. Check our GitHub repo and join the thousands of developers in our community.