Acelere Unity en GitHub Actions
Última actualización
Para acelerar Unity en GitHub Actions, guarde en caché la carpeta Library con actions/cache, mantenga una caché por cada plataforma de compilación, descargue los archivos de Git LFS solo cuando sea necesario y ejecute cada plataforma como un job independiente con unity-builder de GameCI. La carpeta Library contiene los recursos importados, y volver a generarla desde cero suele ser el paso más largo de una ejecución de CI en Unity.
Esta guía utiliza GameCI, el conjunto de herramientas de CI para Unity de código abierto. Para ver el enfoque general, consulte cómo acelerar GitHub Actions.
Por qué el CI de Unity es lento
Una compilación de Unity desde cero realiza cuatro operaciones costosas: descargar una imagen de Docker del editor (de varios gigabytes), activar una licencia, importar todos los recursos a Library y, después, compilar los scripts y generar el reproductor. La importación es el factor más pesado en proyectos con muchas texturas, modelos y archivos de audio. La descarga de la imagen del editor ocupa el segundo lugar. Ninguno de los dos se resuelve con un compilador más rápido; se resuelven con cachés y haciendo menos trabajo en cada job.
La caché de Library
La documentación del builder de GameCI muestra un flujo de trabajo que guarda en caché Library con actions/cache. La clave incluye la plataforma de destino y un hash del contenido del proyecto, con un prefijo de restore-keys para la plataforma:
- uses: actions/cache@v6
with:
path: Library
key: Library-${{ matrix.targetPlatform }}-${{ hashFiles('Assets/**', 'Packages/**', 'ProjectSettings/**') }}
restore-keys: |
Library-${{ matrix.targetPlatform }}-
Tres puntos de este diseño:
- La plataforma forma parte de la clave. Cada destino de compilación (Android, iOS, WebGL, StandaloneLinux64) importa los recursos de forma distinta. Una caché compartida se invalidaría constantemente al cambiar de plataforma.
- Las restore keys hacen el trabajo real. Las entradas de caché son inmutables, por lo que una coincidencia exacta es poco frecuente en cuanto cambia cualquier recurso. La coincidencia por prefijo restaura la
Libraryanterior más próxima, y Unity solo reimporta lo que ha cambiado. - Coste del hash.
hashFilessobreAssets/**lee todos los archivos. En un proyecto grande, con muchos gigabytes de recursos, calcular el hash ya lleva su tiempo. Una clave más económica usaProjectSettings/ProjectVersion.txtyPackages/packages-lock.json, además degithub.shapara guardar, con el prefijo como restore key.
Las cachés de Library suelen ser grandes, a menudo de 1 GB o más por plataforma, y GitHub limita el almacenamiento total de caché por repositorio; consulte los límites de caché de GitHub Actions. Con tres plataformas y tráfico de PR, pueden expulsarse entradas útiles con rapidez. Guarde la caché solo en main con actions/cache/save y restáurela en todas partes con actions/cache/restore.
Activación de la licencia
GameCI documenta dos vías, usando secretos del repositorio:
- Licencia personal. Actívela una vez mediante el flujo de trabajo de activación de GameCI o en local, y luego almacene
UNITY_LICENSE(el contenido del archivo.ulf),UNITY_EMAILyUNITY_PASSWORD. - Profesional (Plus o Pro). Almacene
UNITY_SERIAL,UNITY_EMAILyUNITY_PASSWORD. Un puesto Pro se utiliza mientras se ejecuta el job; GameCI incluye un paso para devolver la licencia en el builder y en el ejecutor de pruebas. - Servidor de licencias. Si ejecuta un servidor de licencias flotantes, la entrada
unityLicensingServerapunta la compilación hacia él.
GameCI indica que no obtiene ni almacena sus credenciales. Las condiciones de licencia de Unity cambian, así que revise las condiciones vigentes de Unity para uso en CI antes de depender de una licencia personal para un equipo. Los jobs paralelos con un serial Pro pueden necesitar un puesto cada uno.
Git LFS y checkout
Los proyectos de Unity suelen guardar texturas, modelos y audio en Git LFS. El ejemplo de GameCI hace el checkout con lfs: true; sin ello, los archivos son punteros y la compilación falla. Descargue con cuidado:
- uses: actions/checkout@v7
with:
lfs: true
actions/checkout tiene lfs en false por defecto y fetch-depth en 1, de modo que el checkout es superficial. El ejemplo de GameCI usa fetch-depth: 0 para obtener el historial completo, algo que solo necesita si su versionado lee el historial de Git (por ejemplo, para calcular una versión a partir de etiquetas). En caso contrario, mantenga el valor por defecto; un checkout superficial es más rápido. Las descargas de LFS consumen su cuota de ancho de banda de LFS, que es un límite independiente de Actions. Guarde en caché los objetos LFS (.git/lfs) con clave en un hash de .lfs-assets-id si el ancho de banda o el tiempo son un problema, o use un servicio con caché local de Git.
Un job por plataforma
Una matriz asigna a cada destino su propio job, caché y máquina:
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 }}
La entrada unityVersion del builder tiene como valor por defecto auto, que lee ProjectSettings/ProjectVersion.txt. La documentación de GameCI usa game-ci/unity-builder@v4 en este ejemplo y menciona v6 en otras secciones, así que confirme la etiqueta actual en las releases de la acción antes de copiar este código. timeout-minutes es importante aquí: un paso de licencia bloqueado puede consumir una hora.
Notas sobre plataformas: los runners de Linux compilan Standalone Linux, WebGL y Android. Los destinos de Windows y macOS necesitan sus propios runners, y iOS requiere macOS, que cuesta más por minuto; consulte runners de macOS para el CI de iOS.
Pruebas
Ejecute las pruebas de EditMode (rápidas, sin reproductor) en cada PR con el ejecutor de pruebas de GameCI, y las pruebas de PlayMode con menor frecuencia. El ejecutor de pruebas también usa la caché de Library; asígnele el mismo paso de caché para que las pruebas no provoquen una importación completa.
Lo que aportan más núcleos de CPU
La importación de recursos y la compilación de scripts usan varios núcleos, y las compilaciones IL2CPP de Unity son pesadas, así que una máquina más potente ayuda. La velocidad del disco y la RAM también importan, ya que Library es grande. No tenemos una fila de Unity en nuestros benchmarks, así que no citamos una aceleración concreta. Si lo prueba, tenga en cuenta que la imagen del editor es grande; las máquinas virtuales nuevas la descargan en cada ejecución, salvo que la máquina conserve una caché de Docker. Los runners de compiler.dev incluyen cachés de capas de Docker listas, y el cambio es una sola línea: runs-on: [self-hosted, Linux, compiler-ci]. Consulte precios y comparativa, y lea caché de capas de Docker en CI para entender cómo se comportan las descargas de imágenes. Consulte también nuestra página sobre pruebas de QA de juegos.
Preguntas frecuentes
¿Qué debo guardar en caché para Unity en GitHub Actions?
La carpeta Library, con la plataforma de destino en la clave y un prefijo de plataforma como restore key. No comparta una misma caché entre plataformas.
¿Necesito Git LFS para el CI de Unity?
Sí, si su repositorio almacena los recursos en LFS. Establezca lfs: true en checkout; de lo contrario, las compilaciones verán archivos de puntero en lugar de los recursos.
¿Puedo usar una licencia gratuita de Unity en CI?
GameCI admite licencias personales mediante los secretos UNITY_LICENSE, UNITY_EMAIL y UNITY_PASSWORD. Consulte los términos de Unity para su caso de uso.
¿Por qué la caché de Unity nunca acierta?
Las entradas inmutables y una clave que calcula el hash de cada recurso hacen que las coincidencias exactas sean poco frecuentes. Confíe en el prefijo restore-keys y asegúrese de que coincida con la plataforma.
Relacionado
- Acelere un monorepo de TypeScript en GitHub ActionsAcelere la comprobación de tipos y el linting en un monorepo TypeScript con GitHub Actions: tsc incremental, referencias de proyecto y cachés.
- Acelere Playwright en un monorepo con GitHub ActionsAcelere las pruebas e2e de Playwright en un monorepo Node con GitHub Actions: compile la app una vez y omita e2e si no cambió.
- Añada una insignia de velocidad de CI a su READMEMuestre la velocidad de su CI con una insignia en el README: el tiempo mediano de ejecución en GitHub Actions, actualizado automáticamente. Gratis.
- Acelere .NET en GitHub ActionsAcelere las compilaciones de .NET en GitHub Actions: caché de NuGet con setup-dotnet, --no-restore, --no-build, dotnet test en paralelo y servicios SQL.