npm-Abhängigkeiten in GitHub Actions cachen
Zuletzt aktualisiert am
Um npm-Abhängigkeiten in GitHub Actions zu cachen, fügen Sie cache: npm zu actions/setup-node hinzu und installieren mit npm ci. Dabei wird npms Download-Verzeichnis (~/.npm) gecacht, mit dem Schlüssel aus Ihrer package-lock.json. Wenn Sie Kontrolle über den Schlüssel oder den Pfad brauchen, erreicht die explizite actions/cache-Variante unten dasselbe.
Diese Seite beschreibt das npm-spezifische Rezept. Wie Schlüssel, Geltungsbereich und restore-keys allgemein funktionieren, lesen Sie zuerst unter Caching in GitHub Actions.
Option 1: Integriertes Caching von setup-node
name: CI
on: [push, pull_request]
jobs:
test:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v6
- uses: actions/setup-node@v7
with:
node-version: 22
cache: npm
- run: npm ci
- run: npm test
Die Action bildet den Hash aus package-lock.json (oder npm-shrinkwrap.json) im Repository-Root, um den Schlüssel zu erzeugen. In einem Monorepo oder wenn die Lockdatei nicht im Root liegt, verweisen Sie auf die richtige Datei:
- uses: actions/setup-node@v7
with:
node-version: 22
cache: npm
cache-dependency-path: |
package-lock.json
apps/web/package-lock.json
cache-dependency-path wirkt nur, wenn cache gesetzt ist. Laut README von setup-node (Stand Oktober 2026) kann das npm-Caching auch automatisch aktiviert werden, wenn package.json npm im Feld packageManager angibt; das lässt sich mit package-manager-cache: false abschalten. Wenn Sie cache: npm explizit setzen, bleibt das Verhalten offensichtlich.
Option 2: explizites actions/cache
Verwenden Sie diese Option, wenn Sie einen eigenen Schlüssel, getrenntes Wiederherstellen und Speichern benötigen oder setup-node nicht verwenden.
- uses: actions/setup-node@v7
with:
node-version: 22
- name: Get npm cache directory
id: npm-cache
run: echo "dir=$(npm config get cache)" >> "$GITHUB_OUTPUT"
- uses: actions/cache@v6
with:
path: ${{ steps.npm-cache.outputs.dir }}
key: npm-${{ runner.os }}-node22-${{ hashFiles('**/package-lock.json') }}
restore-keys: |
npm-${{ runner.os }}-node22-
- run: npm ci
Die Abfrage des npm-Cache-Verzeichnisses vermeidet, ~/.npm fest zu codieren, was auf Windows-Runnern falsch ist. Der Schlüssel enthält das Betriebssystem, die Node-Hauptversion und den Hash der Lockdatei. Die Zeile restore-keys bewirkt, dass eine Änderung an einem einzelnen Paket den Großteil des Caches von gestern wiederherstellt, sodass npm ci nur die Differenz herunterlädt.
Cachen Sie ~/.npm, nicht node_modules
Der verbreitete Rat, node_modules zu cachen, geht bei npm nach hinten los. npm ci löscht node_modules vor der Installation, daher wird eine wiederhergestellte Kopie verworfen. Sie zahlen erst für Download und Entpacken und dann noch einmal für das Neuaufbauen.
Das Cachen von ~/.npm ist anders. npm ci entpackt weiterhin jedes Paket, liest die Tarballs aber von der lokalen Platte statt aus der Registry. Genau dort geht die Netzwerkzeit verloren.
| Cache | Funktioniert mit npm ci | Hinweise |
|---|---|---|
~/.npm | Ja | Klein, sicher über Node-Versionen hinweg |
node_modules | Nein | Wird bei der Installation gelöscht; native Module brechen zwischen Node-Versionen |
.next/cache, .vite, .eslintcache | Ja, separat | Build- und Lint-Caches, keine Abhängigkeiten |
Wenn die Installationszeit trotz Caching ein Problem bleibt, ist der Entpackschritt CPU- und festplattengebunden. Das ist ein Maschinenproblem, kein Cache-Problem.
So überprüfen Sie einen Cache-Treffer
- Öffnen Sie im Job-Log den Schritt setup-node oder cache. Ein Treffer gibt
Cache restored from key: ...aus. Ein Fehlschlag gibtCache not found for input keys: ...aus. - Bei
actions/cacheist der Ausgabewertcache-hitnur bei exakter Schlüsselübereinstimmung'true'. Eine Teilübereinstimmung überrestore-keysergibt'false', obwohl Dateien wiederhergestellt wurden. - Bei einem Fehlschlag suchen Sie am Ende im Post-Schritt nach
Cache saved with key: .... - Listen Sie die vorhandenen Einträge mit der CLI auf:
gh cache list --key npm- --limit 20
Führen Sie den Workflow zweimal mit derselben Lockdatei aus. Der zweite Lauf sollte „restored“ melden, und der Installationsschritt sollte deutlich kürzer werden.
Häufige Fehler
- Verwendung von
npm installstattnpm ci.npm installkann die Lockdatei umschreiben, sodass Schlüssel und installierter Baum auseinanderlaufen. - Eine Lockdatei, die nicht committet ist.
hashFilesliefert dann eine leere Zeichenkette, jeder Lauf nutzt denselben Schlüssel, und der Cache wird nie aktualisiert. setup-node bricht in diesem Fall mit einem Fehler ab, was hilfreich ist. - Verschiedene Node-Hauptversionen teilen sich einen Schlüssel. Nehmen Sie die Version in den Schlüssel auf, wenn Sie eine Matrix verwenden.
- Caches, die nur bei Pull Requests entstehen. PR-Caches sind auf den Merge-Ref beschränkt und für andere PRs nicht sichtbar. Stellen Sie sicher, dass Pushes auf
maindenselben Cache-Schritt ausführen, damit jeder PR einen warmen Cache lesen kann. - Binärdateien aus Postinstall-Skripten. Pakete wie Playwright, Cypress und Puppeteer laden Browser außerhalb von
~/.npmherunter. Cachen Sie diese Verzeichnisse separat; siehe Playwright-Tests langsam und Cypress-Tests langsam.
Größe und Entfernung
Ein typischer npm-Cache umfasst einige hundert MB. Das Repository-Limit liegt bei 10 GB; alte Einträge werden nach dem Least-Recently-Used-Prinzip entfernt, und ungenutzte Einträge nach 7 Tagen. Eine Matrix über mehrere Node-Versionen und Betriebssysteme vervielfacht die Einträge schnell. Wie Sie sehen, was Ihr Kontingent belegt, erfahren Sie unter Cache-Limits und Entfernung.
Der Rechner für Einsparungen durch Cache-Treffer zeigt, was eine bessere Trefferquote in Minuten bringt.
FAQ
Soll ich in CI npm ci oder npm install verwenden?
Verwenden Sie npm ci. Es installiert genau das, was die Lockdatei vorgibt, bricht ab, wenn package.json und Lockdatei nicht übereinstimmen, und ist bei sauberen Installationen schneller.
Funktioniert das Caching von setup-node bei Pull Requests aus Forks?
Es stellt Caches wieder her, die der Basis-Branch angelegt hat. Speichervorgänge aus Fork-PRs sind durch die Token-Berechtigungen von GitHub eingeschränkt. Verlassen Sie sich daher darauf, dass main den Cache füllt.
Warum ist npm ci trotz wiederhergestelltem npm-Cache noch langsam?
Der Cache entfernt Downloads, nicht das Entpacken und die Lifecycle-Skripte. Prüfen Sie die Zeit in Postinstall-Skripten oder probieren Sie einen schnelleren Runner aus.
Kann ich npm über verschiedene Workflows hinweg cachen?
Ja. Caches gehören zum Repository. Gleicher Schlüssel und gleicher Pfad, gleicher Cache.
Nächste Schritte
Wenn Sie zusätzlich pnpm oder Yarn verwenden, lesen Sie pnpm-Caching und Yarn-Caching. Die vollständige Liste der Maßnahmen finden Sie unter GitHub Actions beschleunigen. compiler.dev führt Ihre Jobs auf Maschinen mit 8 vCPUs aus, mit bereitem Abhängigkeits-Cache; siehe Preise.
Verwandt
- Cargo- und Rust-Builds in GitHub Actions cachenCargo-Registry, Git-Abhängigkeiten und Target-Verzeichnis in GitHub Actions mit Swatinem/rust-cache oder actions/cache cachen, ohne aufgeblähte Caches.
- Go-Module und Build-Cache in GitHub Actions cachenGo-Module (GOMODCACHE) und Build-Cache (GOCACHE) in GitHub Actions mit setup-go oder actions/cache cachen. Keys, go.sum und Cache-Treffer prüfen.
- Gradle-Builds in GitHub Actions cachenGradle-Abhängigkeiten und Build-Cache in GitHub Actions mit gradle/actions/setup-gradle oder actions/cache cachen. Keys, PRs, Bereinigung, Checks.
- pip-Abhängigkeiten in GitHub Actions cachenpip in GitHub Actions mit setup-python oder actions/cache cachen, dazu die schnellere uv-Option. Schlüssel, Nicht-Cache-Inhalte und Trefferprüfung.