Zum Inhalt springen

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
  • workspaces listet workspace -> target-Paare für Repositories mit mehr als einem Cargo-Workspace auf.
  • shared-key lässt mehrere Jobs einen gemeinsamen Cache nutzen statt eines Caches pro Job-Namen. Sinnvoll, wenn check, clippy und test dieselben Abhängigkeiten bauen. Debug- und Release-Profile unterscheiden sich jedoch, daher sollten Sie nur zwischen Jobs mit demselben Profil teilen.
  • save-if speichert nur von main aus, damit PR-Branches Ihr Kontingent nicht füllen.
  • cache-on-failure speichert 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

PfadCachen?Grund
~/.cargo/registry/index und registry/cacheJaVermeidet erneutes Herunterladen von Crates
~/.cargo/git/dbJaGit-Abhängigkeiten
~/.cargo/registry/srcNeinEntpackte Quellen; Cargo erstellt sie aus dem cache schnell neu
target/-AbhängigkeitenJaDer große Gewinn: kompilierte Abhängigkeits-Crates
target/ eigener CratesNeinÄndert sich mit jedem Commit und bläht den Cache auf
target/**/incrementalNeinGroß und in CI selten nützlich
~/.cargo/binVorsichtInstallierte 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:

  1. Debug-Informationen für CI deaktivieren: CARGO_PROFILE_DEV_DEBUG=0 (oder debug = "line-tables-only"). Das verkleinert die Artefakte und beschleunigt das Linken.
  2. Verwenden Sie sccache als Compiler-Wrapper mit dem Cache-Backend von GitHub Actions, statt target zu cachen. Dabei werden Kompilierergebnisse pro Crate zwischengespeichert statt ganzer Verzeichnisse.
  3. Nur ~/.cargo cachen und das Neu-Bauen der Abhängigkeiten in Kauf nehmen. Oft schlechter, dafür günstiger beim Kontingent.
  4. 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 --locked schlägt fehl, wenn Cargo.lock veraltet ist, sodass CI nie stillschweigend neu auflöst.
  • cargo nextest führt Tests parallel über alle Binaries hinweg aus; kombinieren Sie es bei großen Test-Suiten mit Test-Sharding.
  • Verwenden Sie cargo check für reine Lint-Jobs. Dabei entfällt die Codegenerierung.
  • mold oder lld als Linker verkürzt die Linkzeit großer Binaries.

So überprüfen Sie einen Cache-Treffer

  1. rust-cache protokolliert Cache restored from key: ... (achten Sie auf Restoring cache und den Schlüssel, auf den getroffen wurde) sowie eine Zusammenfassung im Post-Schritt, was gespeichert wurde oder warum nicht.
  2. In der Build-Ausgabe zeigt ein warmer Lauf Compiling nur für Ihre eigenen Crates. Ein kalter Lauf listet jede Abhängigkeit auf.
  3. Vergleichen Sie die Dauer von cargo build zwischen Läufen mit derselben Lockfile.
  4. gh cache list --key rust --limit 20 zeigt Größe und letzte Nutzung.

Häufige Fehler

  1. Verschiedene Jobs teilen sich einen Schlüssel. Debug- und Release-Builds oder clippy und test machen sich gegenseitig den Cache ungültig. Verwenden Sie profilspezifische Schlüssel.
  2. Keine Verwendung von --locked. Eine Lockfile, die stillschweigend abweicht, verändert die Bedeutung Ihres Schlüssels.
  3. Das gesamte target-Verzeichnis aus jedem PR cachen. PR-Caches werden nicht über PRs hinweg geteilt; speichern Sie aus main. Siehe Caching in GitHub Actions.
  4. 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.

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

Kostenlos testen