Zum Inhalt springen

Go-Module und Build-Cache in GitHub Actions cachen

Zuletzt aktualisiert am

Um Go in GitHub Actions zu cachen, verwenden Sie actions/setup-go. Die Action cached standardmäßig Go-Module und Build-Ausgaben, geschlüsselt über go.sum. Zwei Caches lohnen sich: der Modul-Cache (GOMODCACHE, heruntergeladene Abhängigkeiten) und der Build-Cache (GOCACHE, kompilierte Pakete und Testergebnisse). Der integrierte Cache deckt beides ab.

Option 1: setup-go

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v6
      - uses: actions/setup-go@v7
        with:
          go-version-file: go.mod
          cache-dependency-path: go.sum
      - run: go build ./...
      - run: go test ./...

Laut README von setup-go (geprüft im Oktober 2026) ist cache standardmäßig auf true gesetzt, und die Action cached Go-Module und Build-Ausgaben. Die standardmäßige Abhängigkeitsdatei ist go.mod im Repository-Root. Setzen Sie cache-dependency-path auf go.sum, um über die Prüfsummendatei zu schlüsseln, oder auf ein Glob-Muster, wenn Sie mehrere Module haben:

- uses: actions/setup-go@v7
  with:
    go-version-file: go.mod
    cache-dependency-path: |
      go.sum
      tools/go.sum

Deaktivieren Sie den Cache mit cache: false, was bei Workflows sinnvoll sein kann, die Releases veröffentlichen.

Option 2: explizites actions/cache

Fragen Sie Go nach den Speicherorten seiner Caches, damit die Pfade auf jedem Betriebssystem stimmen:

- uses: actions/setup-go@v7
  with:
    go-version-file: go.mod
    cache: false
- name: Find Go cache paths
  id: go-cache
  run: |
    echo "mod=$(go env GOMODCACHE)" >> "$GITHUB_OUTPUT"
    echo "build=$(go env GOCACHE)" >> "$GITHUB_OUTPUT"
- uses: actions/cache@v6
  with:
    path: |
      ${{ steps.go-cache.outputs.mod }}
      ${{ steps.go-cache.outputs.build }}
    key: go-${{ runner.os }}-${{ runner.arch }}-${{ hashFiles('**/go.sum') }}
    restore-keys: |
      go-${{ runner.os }}-${{ runner.arch }}-
- run: go test ./...

Unter Linux sind das ~/go/pkg/mod und ~/.cache/go-build. Mit cache: false vermeiden Sie zwei sich überschneidende Caches.

Zwei Caches, zwei Aufgaben

Der Modul-Cache ist gut über go.sum geschlüsselt: Er enthält genau das, was die Prüfsummen auflisten. Der Build-Cache funktioniert anders. Go's Build-Cache ist inhaltsadressiert: Ein Eintrag ist nur gültig, wenn Quellcode, Compiler-Flags und Abhängigkeiten den gleichen Hash ergeben. Ein wiederhergestellter Build-Cache vom gestrigen Commit ist also größtenteils noch gültig, und Go baut nur neu, was sich geändert hat.

Deshalb ist ein Präfix-Fallback mit restore-keys besonders nützlich für GOCACHE. Eine Änderung von go.sum macht die meisten kompilierten Pakete nicht ungültig; ein veralteter Eintrag ist unschädlich, weil Go die Inhalts-Hashes prüft.

CacheInhaltSpartSchlüssel
GOMODCACHEHeruntergeladene ModulquellenNetzwerkzeitgo.sum
GOCACHEKompilierte Pakete, TestergebnisseKompilier- und Testzeitgo.sum + Fallback-Präfix

Testergebnisse in GOCACHE sind echt: go test meldet (cached) für Pakete, deren Eingaben sich nicht geändert haben. In CI können dadurch ganze Pakete übersprungen werden, aber nur mit denselben Flags. Beachten Sie, dass -race-Builds eigene Cache-Einträge verwenden und -count=1 das Caching von Testergebnissen deaktiviert. Wenn Sie bei jedem Lauf frische Ergebnisse brauchen, kostet das Zeit.

Beschleunigung über den Cache hinaus

  • go mod download als eigenen Schritt auszuführen macht die Abhängigkeitszeit in den Logs sichtbar.
  • go test -race ist absichtlich langsamer (oft 2- bis 10-mal). Bei der gemessenen Ausführung von React, Go und Postgres mit go test -race auf compiler.dev sank die CI-Laufzeit von 6m13s auf 2m42s, vor allem durch mehr CPU (siehe Benchmarks).
  • Teilen Sie Pakete mit Test-Sharding auf mehrere Jobs auf; go list ./... liefert eine natürliche Aufteilung.
  • -p steuert die Build-Parallelität; der Standardwert ist GOMAXPROCS, der sich an der Kernanzahl orientiert.
  • Bei sehr großen Repositories sollten Sie einen Remote-Cache erwägen (GOCACHEPROG wird in neueren Go-Versionen unterstützt), statt alles über den 10-GB-Cache von GitHub zu schieben.

So überprüfen Sie einen Cache-Treffer

  1. Der setup-go-Schritt protokolliert bei einem Treffer Cache restored from key: setup-go-Linux-... und bei einem Fehlschlag Cache not found. Sein Post-Schritt protokolliert Cache saved.
  2. Führen Sie go build -x lokal oder in einem Debug-Job aus: wiederhergestellte Pakete werden nicht neu kompiliert. go test gibt (cached) für unveränderte Pakete aus.
  3. go mod download sollte bei warmem GOMODCACHE deutlich unter einer Sekunde abgeschlossen sein.
  4. gh cache list --key setup-go --limit 20 zeigt Größe und letzte Nutzung.

Häufige Fehler

  1. Hashing von go.mod, wenn der Modulgraph in go.sum steht. Beide ändern sich in den meisten Repositories gemeinsam, aber go.sum ist der Prüfsummen-Nachweis; schlüsseln Sie für explizite Caches darauf.
  2. Ein vendoriertes Repository mit Cache. Wenn go mod vendor committet ist, gibt es keinen Modul-Download zu cachen. Cachen Sie nur GOCACHE.
  3. Caching von GOPATH/bin. Mit go install installierte Tools sollten über die Tool-Version geschlüsselt werden.
  4. Mehrere Go-Versionen in einem Schlüssel. Der Build-Cache ist intern nach Go-Version aufgeteilt, aber das Mischen in einem Eintrag verschwendet Speicher. Nehmen Sie die Version bei Matrizen in den Schlüssel auf.
  5. Nur bei PRs speichern. Befüllen Sie den Cache von main. Siehe Caching in GitHub Actions.

FAQ

Cached setup-go standardmäßig?

Ja. Die Eingabe cache ist standardmäßig auf true gesetzt. Setzen Sie cache: false, um sie zu deaktivieren.

Sollte ich GOCACHE oder nur die Module cachen?

Beides. Modul-Downloads sind bei einer guten Netzwerkverbindung schnell; die Zeit geht beim Kompilieren verloren, und GOCACHE spart genau diese Zeit.

Warum läuft go test trotzdem jedes Mal?

Das Caching von Tests wird übersprungen bei -count=1, bei geänderten Dateien oder Umgebungsvariablen, die der Test liest, sowie bei Tests, die Dateien außerhalb des Moduls öffnen. Prüfen Sie, ob -count=1 in Ihrem Befehl steht.

Wie groß wird der Go-Cache?

Meist einige hundert MB, bei CGo oder vielen Testbinaries auch mehr. Siehe Cache-Limits.

Nächste Schritte

Siehe auch Go-CI von Anfang bis Ende beschleunigen. Cargo hat eine ähnliche Aufteilung: Rust-Builds cachen. Eine Checkliste für den gesamten Ablauf finden Sie unter GitHub Actions beschleunigen. compiler.dev führt denselben Job auf 8 vCPU für $0.008 pro Minute aus; siehe Preise.

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

Kostenlos testen