Cargo- und Rust-Builds in GitHub Actions cachen
Zuletzt aktualisiert am
Um Cargo in GitHub Actions zu cachen, ist die einfachste Option Swatinem/rust-cache. Die Action cacht die Cargo-Registry, Git-Abhängigkeiten und die kompilierten Abhängigkeiten in target und bereinigt den Cache vor dem Speichern. Die explizite Variante mit actions/cache funktioniert ebenfalls, aber wenn man target blind cacht, wird der Cache riesig und langsam.
Option 1: Swatinem/rust-cache
jobs:
test:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v6
- uses: dtolnay/rust-toolchain@stable
- uses: Swatinem/rust-cache@v2
- run: cargo test --locked
Laut README von rust-cache (Stand Oktober 2026) cacht die Action ~/.cargo (installierte Binaries, Registry-Index und Crate-Cache sowie Git-Abhängigkeiten, wobei registry/src ausgelassen wird) und ./target. Eigene Workspace-Crates werden nicht gecacht, nur deren Abhängigkeiten. Der Schlüssel wird aus dem Job-Namen, der Rust-Version und dem Hash von Cargo.lock sowie den Manifest-Dateien gebildet, außerdem wird CARGO_INCREMENTAL=0 gesetzt.
Vor dem Speichern entfernt die Action alles, was keine aktuelle Abhängigkeit ist, inkrementelle Artefakte sowie Build-Artefakte, die älter als eine Woche sind. Diese Bereinigung ist der Hauptgrund, warum man sie einem handgeschriebenen Cache vorzieht.
Eingaben, die Sie tatsächlich brauchen:
- uses: Swatinem/rust-cache@v2
with:
workspaces: |
. -> target
tools/xtask -> target
shared-key: ci
save-if: ${{ github.ref == 'refs/heads/main' }}
cache-on-failure: true
workspaceslistetworkspace -> target-Paare für Repositories mit mehr als einem Cargo-Workspace auf.shared-keylässt mehrere Jobs einen gemeinsamen Cache nutzen statt eines Caches pro Job-Namen. Sinnvoll, wenncheck,clippyundtestdieselben Abhängigkeiten bauen. Debug- und Release-Profile unterscheiden sich jedoch, daher sollten Sie nur zwischen Jobs mit demselben Profil teilen.save-ifspeichert nur vonmainaus, damit PR-Branches Ihr Kontingent nicht füllen.cache-on-failurespeichert auch dann, wenn der Job fehlschlägt. Das ist nützlich, weil ein fehlgeschlagener Testlauf trotzdem alle Abhängigkeiten kompiliert hat.
Option 2: explizites actions/cache
- uses: actions/cache@v6
with:
path: |
~/.cargo/registry/index/
~/.cargo/registry/cache/
~/.cargo/git/db/
target/
key: cargo-${{ runner.os }}-${{ runner.arch }}-${{ hashFiles('**/Cargo.lock') }}
restore-keys: |
cargo-${{ runner.os }}-${{ runner.arch }}-
- run: cargo build --locked
Dies ist das Muster, das die eigenen Empfehlungen von Cargo und die Beispiele von actions/cache verwenden. Der Schlüssel enthält Betriebssystem, Architektur und Cargo.lock. Fügen Sie die Compiler-Version (rustc --version) hinzu, wenn Sie den Toolchain nicht mit rust-toolchain.toml festlegen, da von einem rustc erzeugte Artefakte mit einem anderen nicht wiederverwendet werden.
Was gecacht werden sollte und was nicht
| Pfad | Cachen? | Grund |
|---|---|---|
~/.cargo/registry/index und registry/cache | Ja | Vermeidet erneutes Herunterladen von Crates |
~/.cargo/git/db | Ja | Git-Abhängigkeiten |
~/.cargo/registry/src | Nein | Entpackte Quellen; Cargo erstellt sie aus dem cache schnell neu |
target/-Abhängigkeiten | Ja | Der große Gewinn: kompilierte Abhängigkeits-Crates |
target/ eigener Crates | Nein | Ändert sich mit jedem Commit und bläht den Cache auf |
target/**/incremental | Nein | Groß und in CI selten nützlich |
~/.cargo/bin | Vorsicht | Installierte Tools nach Version cachen, nicht pauschal |
Die Falle des "rollierenden Caches": Bei einem expliziten Schlüssel auf Cargo.lock wird der Cache nur gespeichert, wenn sich die Lockdatei ändert. Ihre Workspace-Crates werden nie gespeichert, was genau das Gewünschte ist. Verwenden Sie stattdessen github.sha als Schlüssel, wächst der Cache mit den Build-Ausgaben jedes Commits. rust-cache vermeidet dies durch die Bereinigung vor dem Speichern.
Wenn target zu groß wird
Ein Rust-target-Verzeichnis eines großen Workspaces kann mehrere GB umfassen, und die Wiederherstellungszeit wächst mit ihm. Optionen:
- Debug-Informationen für CI deaktivieren:
CARGO_PROFILE_DEV_DEBUG=0(oderdebug = "line-tables-only"). Das verkleinert die Artefakte und beschleunigt das Linken. - Verwenden Sie
sccacheals Compiler-Wrapper mit dem Cache-Backend von GitHub Actions, statttargetzu cachen. Dabei werden Kompilierergebnisse pro Crate zwischengespeichert statt ganzer Verzeichnisse. - Nur
~/.cargocachen und das Neu-Bauen der Abhängigkeiten in Kauf nehmen. Oft schlechter, dafür günstiger beim Kontingent. - Auf mehr Kernen ausführen. Die Kompilierzeit skaliert mit der CPU; siehe schnellere Runner. Im von compiler.dev gemessenen Lauf für React plus Rust (Axum) mit Postgres sank die gesamte CI-Laufzeit von 2m37s auf 1m45s (siehe Benchmarks).
Weitere Beschleunigungen, die wichtiger sind als der Cache
cargo test --lockedschlägt fehl, wennCargo.lockveraltet ist, sodass CI nie stillschweigend neu auflöst.cargo nextestführt Tests parallel über alle Binaries hinweg aus; kombinieren Sie es bei großen Test-Suiten mit Test-Sharding.- Verwenden Sie
cargo checkfür reine Lint-Jobs. Dabei entfällt die Codegenerierung. moldoderlldals Linker verkürzt die Linkzeit großer Binaries.
So überprüfen Sie einen Cache-Treffer
- rust-cache protokolliert
Cache restored from key: ...(achten Sie aufRestoring cacheund den Schlüssel, auf den getroffen wurde) sowie eine Zusammenfassung im Post-Schritt, was gespeichert wurde oder warum nicht. - In der Build-Ausgabe zeigt ein warmer Lauf
Compilingnur für Ihre eigenen Crates. Ein kalter Lauf listet jede Abhängigkeit auf. - Vergleichen Sie die Dauer von
cargo buildzwischen Läufen mit derselben Lockfile. gh cache list --key rust --limit 20zeigt Größe und letzte Nutzung.
Häufige Fehler
- Verschiedene Jobs teilen sich einen Schlüssel. Debug- und Release-Builds oder
clippyundtestmachen sich gegenseitig den Cache ungültig. Verwenden Sie profilspezifische Schlüssel. - Keine Verwendung von
--locked. Eine Lockfile, die stillschweigend abweicht, verändert die Bedeutung Ihres Schlüssels. - Das gesamte
target-Verzeichnis aus jedem PR cachen. PR-Caches werden nicht über PRs hinweg geteilt; speichern Sie ausmain. Siehe Caching in GitHub Actions. - Das Kontingent wird ausgeschöpft. Rust-Caches sind groß. Lesen Sie die Cache-Limits.
FAQ
Sollte ich das target-Verzeichnis cachen?
Ja, cachen Sie die Artefakte der Abhängigkeiten darin, und lassen Sie ein Tool wie rust-cache die Ausgabe Ihrer eigenen Crates entfernen. Alles zu cachen lässt den Cache ohne Obergrenze wachsen.
Ist sccache besser als rust-cache?
Sie lösen unterschiedliche Probleme. rust-cache stellt ein Verzeichnis wieder her; sccache cacht einzelne Compile-Units und funktioniert branch- und profilübergreifend. Bei großen Workspaces kann sccache die bessere Wahl sein; für die meisten Projekte ist rust-cache einfacher.
Warum ist CARGO_INCREMENTAL=0 wichtig?
Inkrementelle Kompilierung schreibt große Artefakte, die lokale Neubauten beschleunigen, auf einer frischen CI-Maschine aber kaum nützen.
Wie cache ich cargo install-Tools?
Verwenden Sie das Tool und seine Version als Schlüssel oder nutzen Sie eine Action mit vorkompilierten Binaries wie taiki-e/install-action.
Nächste Schritte
Weiterführende Lektüre: Rust-CI von Anfang bis Ende beschleunigen, Caching von Go-Modulen für ein ähnliches Muster mit zwei Verzeichnissen und wie Sie GitHub Actions beschleunigen. Um Rust-CI auf 8-vCPU-Maschinen auszuprobieren, siehe compiler.dev-Preise.
Verwandt
- 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.
- 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.