Saltar al contenido

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 Library anterior más próxima, y Unity solo reimporta lo que ha cambiado.
  • Coste del hash. hashFiles sobre Assets/** 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 usa ProjectSettings/ProjectVersion.txt y Packages/packages-lock.json, además de github.sha para 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_EMAIL y UNITY_PASSWORD.
  • Profesional (Plus o Pro). Almacene UNITY_SERIAL, UNITY_EMAIL y UNITY_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 unityLicensingServer apunta 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.

Ejecute este workflow en compiler.dev Sin tarjeta · 200 minutos gratuitos

Pruébelo gratis