Zum Inhalt springen

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.

CacheFunktioniert mit npm ciHinweise
~/.npmJaKlein, sicher über Node-Versionen hinweg
node_modulesNeinWird bei der Installation gelöscht; native Module brechen zwischen Node-Versionen
.next/cache, .vite, .eslintcacheJa, separatBuild- 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

  1. Öffnen Sie im Job-Log den Schritt setup-node oder cache. Ein Treffer gibt Cache restored from key: ... aus. Ein Fehlschlag gibt Cache not found for input keys: ... aus.
  2. Bei actions/cache ist der Ausgabewert cache-hit nur bei exakter Schlüsselübereinstimmung 'true'. Eine Teilübereinstimmung über restore-keys ergibt 'false', obwohl Dateien wiederhergestellt wurden.
  3. Bei einem Fehlschlag suchen Sie am Ende im Post-Schritt nach Cache saved with key: ....
  4. 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

  1. Verwendung von npm install statt npm ci. npm install kann die Lockdatei umschreiben, sodass Schlüssel und installierter Baum auseinanderlaufen.
  2. Eine Lockdatei, die nicht committet ist. hashFiles liefert 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.
  3. Verschiedene Node-Hauptversionen teilen sich einen Schlüssel. Nehmen Sie die Version in den Schlüssel auf, wenn Sie eine Matrix verwenden.
  4. 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 main denselben Cache-Schritt ausführen, damit jeder PR einen warmen Cache lesen kann.
  5. Binärdateien aus Postinstall-Skripten. Pakete wie Playwright, Cypress und Puppeteer laden Browser außerhalb von ~/.npm herunter. 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.

Diesen Workflow auf compiler.dev ausführen Keine Karte nötig · 200 kostenlose Minuten

Kostenlos testen