guides

Zwei Dateien liegen in fast jedem JavaScript-Projekt nebeneinander, und der Abstand zwischen ihnen ist der Abstand zwischen dem, was Sie verlangt haben, und dem, was Sie bekommen haben. package.json erklärt eine Absicht: die Abhängigkeitsbereiche, die Sie akzeptieren, Ihren eigenen Namen und Ihre Version, Ihre Skripte. package-lock.json erklärt ein Ergebnis: die genaue Version jedes aufgelösten Pakets, auch derjenigen, die Sie nie genannt haben, jeweils mit der Registry-URL ihrer Herkunft und einem Integritätswert ihres Inhalts.

Die Verwechslung ist nicht akademisch. Sie ist der Mechanismus, der „Bei mir läuft es“ am Leben hält: Zwei Entwickler mit byteidentischen package.json-Dateien können in node_modules unterschiedliche Bäume vorfinden, denn ein Bereich wie ^4.17.0 akzeptiert alles unterhalb von 5.0.0, und die Antwort hängt davon ab, was die Registry an dem Tag enthielt, an dem der jeweilige Entwickler die Installation ausführte.

Was jede Datei tatsächlich erklärt

package.json trägt Bereiche, und ein Bereich ist eher eine Erlaubnis als eine Entscheidung. ^1.2.3 akzeptiert Patch- und Minor-Updates unterhalb von 2.0.0, ~1.2.3 akzeptiert nur Patches, und ein nacktes 1.2.3 akzeptiert nichts anderes. Was das Manifest nie trägt, ist Ihr transitiver Baum: Die Abhängigkeiten Ihrer Abhängigkeiten stehen nicht darin, und sie deklarieren eigene Bereiche — dort entsteht der größte Teil der Versionsdrift.

package-lock.json trägt die Auflösung. Jedes Paket im Baum erhält einen Eintrag mit der gewählten Version, der URL des heruntergeladenen Archivs und einer Integritätszeichenkette, die der Installer gegen die empfangenen Bytes prüft. Dieser Wert macht die Lockfile zu einem Lieferketten-Artefakt statt zu einer bloßen Bequemlichkeit: Ein unter derselben Versionsnummer mit anderem Inhalt neu veröffentlichtes Archiv fällt bei der Prüfung durch, statt sich stillschweigend zu installieren.

Die beiden Dateien haben auch nicht denselben Autor. Sie bearbeiten package.json. Sie bearbeiten package-lock.json nicht — npm schreibt sie, und sie von Hand zu ändern ist ein verlässlicher Weg zu einer Lockfile, die keiner Auflösung mehr entspricht, die npm tatsächlich durchführen würde.

Die Lockfile einchecken

Bei einer Anwendung: einchecken. Ohne Lockfile in der Versionsverwaltung löst Ihre CI den Baum bei jedem Lauf neu auf, und ein stromaufwärts zwischen zwei Builds veröffentlichter Patch verändert das Ausgelieferte, ohne dass sich eine einzige Zeile Ihres Codes bewegt hätte.

• package.json - erklärt die Absicht: die Bereiche, die Sie akzeptieren, Ihre Skripte, Ihre eigenen Metadaten
• package-lock.json - erklärt das Ergebnis: jede aufgelöste Version, ihre Archiv-URL und ihr Integritätswert
• Folge - npm ci schlägt fehl, wenn beide auseinandergehen, und genau das ist der Zweck

Bei einer Bibliothek lautet die Antwort gleich, der Grund ist aber ein anderer, und genau das wird am häufigsten falsch gelesen. Die Lockfile einer veröffentlichten Bibliothek wird von denen, die sie installieren, nicht verwendet — npm ignoriert die Lockfiles von Abhängigkeiten und löst den gesamten Baum aus deren Manifesten auf. Einchecken lohnt sich trotzdem, weil es Ihre eigenen Mitwirkenden und Ihre eigene CI reproduzierbar macht. Ihren Nutzern bringt es schlicht nichts.

package-lock.json in die .gitignore zu setzen hat daher genau einen vertretbaren Zweck: ein Repository, das bewusst bei jedem Lauf die neuesten zulässigen Versionen auflösen will, um früh zu bemerken, wenn eine Veröffentlichung stromaufwärts es bricht. Das ist eine bewusst eingegangene Abwägung mit bekannten Kosten. Es ist keine Voreinstellung.

npm install und npm ci sind nicht derselbe Befehl

npm install liest das Manifest, kann die Lockfile aktualisieren und schreibt klaglos neue Einträge hinein. npm ci liest die Lockfile, weigert sich, sie zu ändern, entfernt node_modules vor der Installation und bricht mit einem Fehler ab, wenn Lockfile und Manifest auseinandergehen. In der Continuous Integration wollen Sie das Zweite, und der Fehler ist das Feature: Eine Abweichung bedeutet, dass ein Bereich geändert wurde, ohne die Sperre neu zu erzeugen.

Deshalb verdient auch ein Pull Request, der package.json anfasst und package-lock.json unberührt lässt, einen zweiten Blick. Entweder wurde das Manifest von Hand bearbeitet, oder die Lockfile wurde neu erzeugt und nie zum Commit hinzugefügt. Beides hinterlässt das Repository in einem Zustand, in dem npm ci für alle anderen fehlschlägt.

Wenn die beiden wirklich auseinandergehen, besteht die Reparatur nicht darin, die Lockfile von Hand zu flicken. Führen Sie den Befehl aus, der sie neu erzeugt — npm install, oder npm install --package-lock-only, wenn Sie die Lockfile auffrischen wollen, ohne node_modules neu zu bauen — und checken Sie das Ergebnis ein. Die Lockfile ist ein Build-Ergebnis, das zufällig versioniert wird, und so sollte man sie behandeln.