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_modulesnicht. 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 WiederherstellungsschrittCache restored from key: .... - Messen Sie
pnpm install. Bei einem warmen Store meldet die Fortschrittszeile von pnpm Pakete alsreusedstatt alsdownloaded. gh cache list --key pnpm- --limit 20zeigt 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
- Reihenfolge der Einrichtung.
actions/setup-nodevorpnpm/action-setupschlägt beicache: pnpmfehl. - 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.
- Verwendung von
pnpm installohne--frozen-lockfile. Seien Sie in CI explizit, damit eine veraltete Lockdatei den Build fehlschlagen lässt, statt stillschweigend neue Versionen aufzulösen. - Cache nur bei Pull Requests schreiben. PR-Caches sind auf die Merge-Referenz des PR beschränkt. Befüllen Sie ihn auch von
mainaus. Details unter Caching in GitHub Actions. - 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).
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.
- npm-Abhängigkeiten in GitHub Actions cachennpm-Abhängigkeiten in GitHub Actions cachen, mit setup-node oder actions/cache. Funktionierendes YAML, der richtige Key, warum nicht node_modules, und Treffer prüfen.