Unity in GitHub Actions beschleunigen
Zuletzt aktualisiert am
Um Unity in GitHub Actions zu beschleunigen, cachen Sie den Ordner Library mit actions/cache, verwenden Sie pro Build-Target einen eigenen Cache, laden Sie Git-LFS-Dateien nur bei Bedarf und führen Sie jede Plattform als eigenen Job mit GameCIs unity-builder aus. Der Ordner Library enthält die importierten Assets. Seine Neuerstellung von Grund auf ist meist der längste Schritt eines Unity-CI-Laufs.
Dieser Leitfaden verwendet GameCI, das quelloffene Unity-CI-Toolkit. Den allgemeinen Ansatz finden Sie unter wie Sie GitHub Actions beschleunigen.
Warum Unity-CI langsam ist
Ein sauberer Unity-Build verursacht vier aufwendige Schritte: das Docker-Image des Editors herunterladen (mehrere Gigabyte), eine Lizenz aktivieren, jedes Asset in Library importieren und anschließend Skripte kompilieren und den Player bauen. Der Import ist bei Projekten mit vielen Texturen, Modellen und Audiodateien der größte Posten, das Herunterladen des Editor-Images der zweitgrößte. Keines davon löst ein schnellerer Compiler; beides lässt sich durch Caches und durch weniger Arbeit pro Job verbessern.
Der Library-Cache
Die Dokumentation des GameCI-Builders zeigt einen Workflow, der Library mit actions/cache cacht. Der Schlüssel enthält die Zielplattform und einen Hash des Projektinhalts, außerdem ein restore-keys-Präfix für die Plattform:
- uses: actions/cache@v6
with:
path: Library
key: Library-${{ matrix.targetPlatform }}-${{ hashFiles('Assets/**', 'Packages/**', 'ProjectSettings/**') }}
restore-keys: |
Library-${{ matrix.targetPlatform }}-
Drei Punkte zu diesem Aufbau:
- Plattform im Schlüssel. Jedes Build-Target (Android, iOS, WebGL, StandaloneLinux64) importiert Assets unterschiedlich. Ein gemeinsamer Cache würde beim Wechsel ständig überschrieben.
- Restore-Keys leisten die eigentliche Arbeit. Cache-Einträge sind unveränderlich, daher ist ein exakter Treffer selten, sobald sich ein Asset ändert. Der Präfix-Abgleich stellt die nächstliegende frühere
Librarywieder her, und Unity importiert nur das neu, was sich geändert hat. - Kosten des Hashings.
hashFilesüberAssets/**liest jede Datei. Bei einem großen Projekt mit vielen Gigabyte an Assets dauert das Hashing selbst eine Weile. Ein günstigerer Schlüssel verwendetProjectSettings/ProjectVersion.txtundPackages/packages-lock.jsonsowiegithub.shazum Speichern, mit dem Präfix als Restore-Key.
Library-Caches sind groß, oft 1 GB oder mehr pro Plattform, und GitHub begrenzt den gesamten Cache-Speicher pro Repository. Lesen Sie dazu die Cache-Limits von GitHub Actions. Bei drei Plattformen und regem PR-Verkehr werden nützliche Einträge schnell verdrängt. Speichern Sie den Cache deshalb nur auf main mit actions/cache/save und stellen Sie ihn überall mit actions/cache/restore wieder her.
Lizenzaktivierung
GameCI beschreibt zwei Wege, jeweils mit Repository-Secrets:
- Persönliche Lizenz. Aktivieren Sie sie einmal über den GameCI-Aktivierungs-Workflow oder lokal und speichern Sie dann
UNITY_LICENSE(den Inhalt der Datei.ulf),UNITY_EMAILundUNITY_PASSWORD. - Professional (Plus oder Pro). Speichern Sie
UNITY_SERIAL,UNITY_EMAILundUNITY_PASSWORD. Ein Pro-Platz wird während der Laufzeit des Jobs belegt; GameCI enthält im Builder und im Test-Runner einen Schritt zur Rückgabe der Lizenz. - Lizenzserver. Wenn Sie einen Floating-License-Server betreiben, verweist die Eingabe
unityLicensingServerden Build darauf.
GameCI gibt an, Ihre Zugangsdaten weder zu beschaffen noch zu speichern. Unitys Lizenzbedingungen ändern sich, prüfen Sie daher vor dem Einsatz einer persönlichen Lizenz im Team die aktuellen Bedingungen von Unity für CI-Nutzung. Parallele Jobs auf einer Pro-Seriennummer benötigen unter Umständen jeweils einen eigenen Platz.
Git LFS und Checkout
Unity-Projekte speichern Texturen, Modelle und Audio häufig in Git LFS. Das GameCI-Beispiel checkt mit lfs: true aus; ohne diese Option sind die Dateien nur Zeiger, und der Build bricht ab. Laden Sie sorgfältig:
- uses: actions/checkout@v7
with:
lfs: true
actions/checkout setzt lfs standardmäßig auf false und fetch-depth auf 1, der Checkout ist also flach. Das GameCI-Beispiel verwendet fetch-depth: 0 für die vollständige Historie, was nur nötig ist, wenn Ihre Versionierung die Git-Historie liest (etwa zur Berechnung einer Version aus Tags). Ansonsten behalten Sie den Standard bei; ein flacher Checkout ist schneller. LFS-Downloads zählen auf Ihr LFS-Bandbreitenkontingent, das getrennt von Actions limitiert ist. Cachen Sie die LFS-Objekte (.git/lfs) über einen Hash von .lfs-assets-id, falls Bandbreite oder Zeit ein Problem sind, oder nutzen Sie einen Dienst mit lokalem Git-Caching.
Ein Job pro Plattform
Eine Matrix gibt jedem Target einen eigenen Job, Cache und eigene Maschine:
name: build
on:
push:
branches: [main]
pull_request:
jobs:
build:
name: Build ${{ matrix.targetPlatform }}
runs-on: ubuntu-latest
timeout-minutes: 60
strategy:
fail-fast: false
matrix:
targetPlatform:
- StandaloneLinux64
- WebGL
- Android
steps:
- uses: actions/checkout@v7
with:
lfs: true
- uses: actions/cache@v6
with:
path: Library
key: Library-${{ matrix.targetPlatform }}-${{ hashFiles('Assets/**', 'Packages/**', 'ProjectSettings/**') }}
restore-keys: |
Library-${{ matrix.targetPlatform }}-
- uses: game-ci/unity-builder@v4
env:
UNITY_LICENSE: ${{ secrets.UNITY_LICENSE }}
UNITY_EMAIL: ${{ secrets.UNITY_EMAIL }}
UNITY_PASSWORD: ${{ secrets.UNITY_PASSWORD }}
with:
targetPlatform: ${{ matrix.targetPlatform }}
- uses: actions/upload-artifact@v7
with:
name: Build-${{ matrix.targetPlatform }}
path: build/${{ matrix.targetPlatform }}
Die Eingabe unityVersion des Builders hat den Standardwert auto und liest ProjectSettings/ProjectVersion.txt. Die GameCI-Dokumentation verwendet in diesem Beispiel game-ci/unity-builder@v4 und nennt an anderen Stellen v6. Prüfen Sie daher vor dem Kopieren den aktuellen Tag in den Releases der Action. timeout-minutes ist hier wichtig: Ein hängender Lizenzschritt kann eine Stunde verbrauchen.
Hinweise zu Plattformen: Linux-Runner bauen Standalone Linux, WebGL und Android. Windows- und macOS-Targets brauchen eigene Runner, und iOS benötigt macOS, was pro Minute mehr kostet. Siehe macOS-Runner für iOS-CI.
Tests
Führen Sie EditMode-Tests (schnell, ohne Player) bei jedem PR mit dem Test-Runner von GameCI aus und PlayMode-Tests seltener. Der Test-Runner nutzt ebenfalls den Library-Cache; geben Sie ihm denselben Cache-Schritt, damit die Tests keinen erneuten Import auslösen.
Was mehr CPU-Kerne bringen
Asset-Import und Skriptkompilierung nutzen mehrere Kerne, und Unitys IL2CPP-Builds sind rechenintensiv, daher hilft eine größere Maschine. Auch Festplattengeschwindigkeit und RAM sind wichtig, da der Ordner Library groß ist. Wir haben keine Unity-Zeile in unseren Benchmarks, daher nennen wir keine Beschleunigung. Wenn Sie es testen, beachten Sie, dass das Editor-Image groß ist; frische VMs laden es bei jedem Lauf neu, sofern die Maschine keinen Docker-Cache vorhält. Die Runner von compiler.dev bringen bereits Docker-Layer-Caches mit, und die Umstellung erfordert eine einzige Zeile: runs-on: [self-hosted, Linux, compiler-ci]. Siehe Preise und Vergleich und lesen Sie Docker-Layer-Caching in CI, um zu verstehen, wie sich Image-Pulls verhalten. Siehe auch unsere Seite zu Game-QA-Tests.
FAQ
Was sollte ich für Unity in GitHub Actions cachen?
Den Ordner Library, mit der Zielplattform im Schlüssel und einem Plattform-Präfix als Restore-Key. Verwenden Sie keinen gemeinsamen Cache für alle Plattformen.
Benötige ich Git LFS für Unity-CI?
Ja, wenn Ihr Repository Assets in LFS speichert. Setzen Sie lfs: true beim Checkout, sonst sehen Builds nur Pointer-Dateien statt der eigentlichen Assets.
Kann ich in der CI eine kostenlose Unity-Lizenz verwenden?
GameCI unterstützt persönliche Lizenzen über die Secrets UNITY_LICENSE, UNITY_EMAIL und UNITY_PASSWORD. Prüfen Sie die Nutzungsbedingungen von Unity für Ihren Anwendungsfall.
Warum trifft mein Unity-Cache nie?
Unveränderliche Einträge und ein Schlüssel, der jedes Asset hasht, führen selten zu exakten Treffern. Verlassen Sie sich auf das Präfix in restore-keys und achten Sie darauf, dass es zur Plattform passt.
Verwandt
- TypeScript-Monorepo in GitHub Actions beschleunigenTypprüfung und Linting in TypeScript-Monorepos auf GitHub Actions beschleunigen: inkrementelles tsc, Projektreferenzen, Lint-Caches und parallele Jobs.
- Playwright im Monorepo mit GitHub Actions beschleunigenPlaywright-E2E-Tests in einem Node-Monorepo auf GitHub Actions beschleunigen: App einmal bauen, E2E überspringen, wenn sich die Web-App nicht ändert.
- CI-Geschwindigkeits-Badge in Ihre README einfügenZeigen Sie die Geschwindigkeit Ihrer CI mit einem README-Badge: die mediane Laufzeit Ihrer Repository-Workflows auf GitHub Actions, automatisch aktualisiert.
- .NET in GitHub Actions beschleunigen.NET-Builds in GitHub Actions beschleunigen: NuGet-Caching mit setup-dotnet, --no-restore, --no-build, paralleles dotnet test und SQL-Server-Services.