Zum Inhalt springen

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 Library wieder her, und Unity importiert nur das neu, was sich geändert hat.
  • Kosten des Hashings. hashFiles über Assets/** liest jede Datei. Bei einem großen Projekt mit vielen Gigabyte an Assets dauert das Hashing selbst eine Weile. Ein günstigerer Schlüssel verwendet ProjectSettings/ProjectVersion.txt und Packages/packages-lock.json sowie github.sha zum 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_EMAIL und UNITY_PASSWORD.
  • Professional (Plus oder Pro). Speichern Sie UNITY_SERIAL, UNITY_EMAIL und UNITY_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 unityLicensingServer den 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.

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

Kostenlos testen