Zum Inhalt springen

pnpm-Abhängigkeiten in GitHub Actions cachen

Zuletzt aktualisiert am

Um pnpm in GitHub Actions zu cachen, installieren Sie zuerst pnpm und setzen dann cache: pnpm bei actions/setup-node. Damit wird der content-adressierbare Store von pnpm gecacht, der über pnpm-lock.yaml identifiziert wird. Die Reihenfolge ist wichtig: setup-node benötigt pnpm, bevor es läuft, daher steht pnpm/action-setup darüber.

Option 1: Cache von setup-node

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v6
      - uses: pnpm/action-setup@v6
      - uses: actions/setup-node@v7
        with:
          node-version: 22
          cache: pnpm
      - run: pnpm install --frozen-lockfile
      - run: pnpm test

pnpm/action-setup kann version weglassen, wenn package.json ein Feld packageManager enthält (zum Beispiel "packageManager": "pnpm@10.9.0"). Das ist die sauberste Einrichtung: Eine Stelle legt die pnpm-Version für Ihren Laptop und für CI fest. Andernfalls übergeben Sie with: { version: 10 }.

Die README von setup-node (geprüft im Oktober 2026) besagt, dass der Cache-Wert pnpm pnpm 6.10 oder neuer voraussetzt und dass pnpm bereits installiert sein muss. Wenn Sie Unable to locate executable file: pnpm sehen, stimmt die Reihenfolge der Schritte nicht.

Option 2: pnpm/action-setup den Store cachen lassen

pnpm/action-setup hat eine eigene Eingabe cache, die standardmäßig deaktiviert ist. Laut README cacht sie das pnpm-Store-Verzeichnis, wobei der Schlüssel aus pnpm-lock.yaml gebildet wird (dies lässt sich mit cache_dependency_path ändern).

- uses: pnpm/action-setup@v6
  with:
    cache: true
- uses: actions/setup-node@v7
  with:
    node-version: 22
- run: pnpm install --frozen-lockfile

Wählen Sie einen Mechanismus, nicht beide. Zwei Caches für denselben Store verschwenden Kontingent.

Option 3: explizites actions/cache

Fragen Sie pnpm nach dem Speicherort des Stores, statt zu raten. Der Ort unterscheidet sich je nach Betriebssystem und pnpm-Version.

- uses: pnpm/action-setup@v6
- uses: actions/setup-node@v7
  with:
    node-version: 22
- name: Get pnpm store path
  id: pnpm-store
  run: echo "path=$(pnpm store path --silent)" >> "$GITHUB_OUTPUT"
- uses: actions/cache@v6
  with:
    path: ${{ steps.pnpm-store.outputs.path }}
    key: pnpm-${{ runner.os }}-${{ hashFiles('**/pnpm-lock.yaml') }}
    restore-keys: |
      pnpm-${{ runner.os }}-
- run: pnpm install --frozen-lockfile

Der Glob hashFiles('**/pnpm-lock.yaml') behandelt Repositories mit mehr als einer Lockdatei. In einem Standard-pnpm-Workspace gibt es eine Lockdatei im Root, daher ist der Hash stabil und ändert sich nur, wenn sich Abhängigkeiten ändern.

Was Sie cachen sollten und was nicht

pnpm speichert jedes Paket nur einmal im Store und verlinkt Dateien (per Hardlink oder Kopie) in das node_modules jedes Projekts. Dieses Design macht es ausreichend, nur den Store zu cachen.

  • Cachen Sie den Store. Er ist der teure Teil: die Downloads aus dem Netzwerk.
  • Cachen Sie node_modules nicht. Es ist ein Baum aus Links in den Store. Aus einem Tarball wiederhergestellt, werden daraus vollständige Kopien, die sehr groß sein können und beim nächsten Lauf möglicherweise nicht zum Store-Layout passen.
  • Tragen Sie den Store-Pfad nicht fest ein. Verwenden Sie pnpm store path.

Ein Vorbehalt: Hardlinks funktionieren nur innerhalb eines Dateisystems. Wenn der Store auf einem anderen Volume wiederhergestellt wird als Ihr Workspace, weicht pnpm auf Kopieren aus. Das ist langsamer, aber weiterhin korrekt.

Workspaces

Für einen Workspace installieren Sie einmal im Root und führen Aufgaben mit Filtern aus:

- run: pnpm install --frozen-lockfile
- run: pnpm --filter "...[origin/main]" test

Damit der Filter funktioniert, braucht der Checkout genügend Historie. Die vollständige Einrichtung einschließlich fetch-depth finden Sie unter schnellste CI für pnpm-Workspaces.

So überprüfen Sie einen Cache-Treffer

  • Der Post-Schritt von setup-node protokolliert bei einem Cache-Fehlschlag Cache saved with key: .... Bei einem Treffer protokolliert der Wiederherstellungsschritt Cache restored from key: ....
  • Messen Sie pnpm install. Bei einem warmen Store meldet die Fortschrittszeile von pnpm Pakete als reused statt als downloaded.
  • gh cache list --key pnpm- --limit 20 zeigt Einträge, Größen und Zeiten des letzten Zugriffs.

Ein vollständiges Beispiel mit Matrix

Caches sind pro Betriebssystem geschlüsselt, daher erzeugt eine Matrix über Node-Versionen einen Eintrag pro Zelle, sofern Sie den Store nicht teilen. Der pnpm-Store ist größtenteils unabhängig von der Node-Version, daher reicht meist ein Schlüssel ohne Node-Version, was Kontingent spart:

jobs:
  test:
    runs-on: ubuntu-latest
    strategy:
      fail-fast: false
      matrix:
        node: [20, 22]
    steps:
      - uses: actions/checkout@v6
      - uses: pnpm/action-setup@v6
      - uses: actions/setup-node@v7
        with:
          node-version: ${{ matrix.node }}
          cache: pnpm
      - run: pnpm install --frozen-lockfile
      - run: pnpm test

setup-node bildet seinen Schlüssel aus Betriebssystem, Paketmanager und Lockdatei-Hash, sodass beide Matrixzellen denselben Store-Eintrag wiederherstellen. Pakete mit nativen Erweiterungen werden bei der Installation pro Node-Version neu gebaut, ihre Downloads stammen aber weiterhin aus dem Cache. Prüfen Sie den Rechner für Cache-Einsparungen, um zu sehen, was die Trefferquote bei Ihrer Anzahl an Läufen bringt.

Häufige Fehler

  1. Reihenfolge der Einrichtung. actions/setup-node vor pnpm/action-setup schlägt bei cache: pnpm fehl.
  2. Abweichende pnpm-Versionen. Das Store-Layout ändert sich zwischen Hauptversionen. Nehmen Sie die pnpm-Hauptversion in Ihren Schlüssel auf, wenn Sie häufig aktualisieren.
  3. Verwendung von pnpm install ohne --frozen-lockfile. Seien Sie in CI explizit, damit eine veraltete Lockdatei den Build fehlschlagen lässt, statt stillschweigend neue Versionen aufzulösen.
  4. Cache nur bei Pull Requests schreiben. PR-Caches sind auf die Merge-Referenz des PR beschränkt. Befüllen Sie ihn auch von main aus. Details unter Caching in GitHub Actions.
  5. Das Limit von 10 GB vergessen. Jede Kombination aus Betriebssystem und Node erzeugt einen neuen Eintrag. Siehe Cache-Limits.

FAQ

Wo liegt der pnpm-Store auf einem von GitHub gehosteten Runner?

Führen Sie pnpm store path in einem Schritt aus, um ihn auszugeben. Er hängt von Betriebssystem und pnpm-Version ab, weshalb das explizite Rezept ihn dynamisch ermittelt.

Ist pnpm in CI schneller als npm?

Bei einem warmen Store oft ja, weil pnpm Dateien verlinkt statt zu kopieren. Der Gewinn hängt von Ihrem Abhängigkeitsbaum ab; messen Sie beide mit demselben Cache-Zustand.

Soll ich den pnpm-Store committen?

Nein. Dafür ist ein Cache der richtige Ort.

Was ist mit Turborepo- oder Nx-Caches?

Diese cachen Task-Ausgaben, nicht Abhängigkeiten. Siehe Monorepo-CI mit Nx oder Turborepo.

Nächste Schritte

Vergleichen Sie es mit den Setups für npm und Yarn. Wenn Installationen schnell sind und der Job trotzdem langsam läuft, liegt der Engpass bei der CPU. compiler.dev führt denselben Workflow auf Maschinen mit 8 vCPU für $0.008 pro Minute aus (siehe Preise).

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

Kostenlos testen