Saltar al contenido

Caché de módulos Go y de compilación en GitHub Actions

Última actualización

Para almacenar en caché Go en GitHub Actions, use actions/setup-go. Por defecto almacena en caché los módulos de Go y los resultados de compilación, con clave basada en go.sum. Hay dos cachés que merece la pena aprovechar: la caché de módulos (GOMODCACHE, dependencias descargadas) y la caché de compilación (GOCACHE, paquetes compilados y resultados de pruebas). La caché integrada cubre ambas.

Opción 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 ./...

Según el README de setup-go (consultado en octubre de 2026), cache tiene como valor predeterminado true, y la acción almacena en caché los módulos de Go y los resultados de compilación. El archivo de dependencias predeterminado es go.mod en la raíz del repositorio; establezca cache-dependency-path en go.sum para usar el archivo de sumas de comprobación como clave, o en un patrón glob si tiene varios módulos:

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

Desactívela con cache: false, lo que puede interesarle en flujos de trabajo que publican versiones.

Opción 2: actions/cache explícito

Pregunte a Go dónde están sus cachés, para que las rutas sean correctas en cada sistema operativo:

- 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 ./...

En Linux, estas son ~/go/pkg/mod y ~/.cache/go-build. Establecer cache: false evita dos cachés superpuestas.

Dos cachés, dos funciones

La caché de módulos se basa bien en go.sum: contiene exactamente lo que enumera el archivo de sumas de comprobación. La caché de compilación es diferente. La caché de compilación de Go está direccionada por contenido: una entrada solo es válida si el código fuente, los indicadores del compilador y las dependencias producen el mismo hash. Por tanto, una caché de compilación restaurada del commit de ayer sigue siendo válida en su mayor parte, y Go simplemente recompila lo que ha cambiado.

Esto significa que una alternativa con prefijo en restore-keys es especialmente útil para GOCACHE. Un cambio en go.sum no invalida la mayoría de los paquetes compilados; una entrada obsoleta no causa problemas, porque Go verifica los hashes del contenido.

CachéContenidoAhorraClave
GOMODCACHECódigo fuente de módulos descargadosTiempo de redgo.sum
GOCACHEPaquetes compilados, resultados de pruebasTiempo de compilación y de pruebasgo.sum + prefijo de alternativa

Los resultados de pruebas en GOCACHE son reales: go test muestra (cached) en los paquetes cuyas entradas no cambiaron. En CI, esto puede omitir paquetes completos, pero solo con los mismos indicadores. Tenga en cuenta que las compilaciones con -race usan entradas de caché distintas de las compilaciones normales, y que -count=1 desactiva la caché de resultados de pruebas. Si necesita resultados nuevos en cada ejecución, cuente con que eso consumirá más tiempo.

Mejoras de velocidad más allá de la caché

  • go mod download como paso independiente hace visible en los registros el tiempo dedicado a las dependencias.
  • go test -race es más lento por diseño (a menudo de 2 a 10 veces). En una ejecución medida por compiler.dev de React, Go y Postgres con go test -race, el CI pasó de 6m13s a 2m42s, principalmente con más CPU (consulte los benchmarks).
  • Divida los paquetes entre trabajos con sharding de pruebas; go list ./... de Go facilita una división natural.
  • -p controla el paralelismo de la compilación; el valor predeterminado es GOMAXPROCS, que depende del número de núcleos.
  • En repositorios muy grandes, considere una caché remota (GOCACHEPROG es compatible en versiones recientes de Go) en lugar de enviar todo a través de la caché de GitHub de 10 GB.

Cómo verificar un acierto de caché

  1. El paso de setup-go registra Cache restored from key: setup-go-Linux-... cuando encuentra la caché, y Cache not found cuando no la encuentra. Su paso posterior registra Cache saved.
  2. Ejecute go build -x en local o en un trabajo de depuración: los paquetes restaurados no se recompilan. go test muestra (cached) en los paquetes sin cambios.
  3. go mod download debería terminar en menos de un segundo cuando GOMODCACHE está caliente.
  4. gh cache list --key setup-go --limit 20 muestra el tamaño y el último uso.

Errores comunes

  1. Calcular el hash de go.mod cuando el grafo de módulos está en go.sum. Ambos cambian juntos en la mayoría de los repositorios, pero go.sum es el registro de sumas de comprobación; use ese archivo como clave para cachés explícitas.
  2. Un repositorio con vendor y caché. Si go mod vendor está confirmado, no hay descarga de módulos que almacenar en caché. Almacene en caché solo GOCACHE.
  3. Almacenar en caché GOPATH/bin. Las herramientas instaladas con go install deben tener como clave la versión de la herramienta.
  4. Varias versiones de Go en una misma clave. La caché de compilación se particiona internamente por versión de Go, pero mezclarlas en una misma entrada desperdicia espacio. Incluya la versión en la clave para las matrices.
  5. Guardar solo en PR. Rellene la caché desde main. Consulte Caché en GitHub Actions.

Preguntas frecuentes

¿setup-go almacena en caché por defecto?

Sí. La entrada cache tiene como valor predeterminado true. Establezca cache: false para desactivarla.

¿Debo almacenar en caché GOCACHE o solo los módulos?

Ambos. La descarga de módulos es rápida con una buena red; el tiempo se invierte en la compilación, y GOCACHE es lo que lo ahorra.

¿Por qué go test sigue ejecutándose en cada ejecución?

La caché de pruebas se omite con -count=1, cuando cambian archivos o variables de entorno que la prueba lee, y en pruebas que abren archivos fuera del módulo. Compruebe si hay -count=1 en su comando.

¿Qué tamaño puede alcanzar la caché de Go?

Normalmente unos cientos de MB, más si usa CGo o muchos binarios de prueba. Consulte límites de la caché.

Próximos pasos

Consulte también cómo acelerar el CI de Go de principio a fin. Cargo tiene una división similar: cómo almacenar en caché las compilaciones de Rust. Para una lista de comprobación completa, consulte cómo acelerar GitHub Actions. compiler.dev ejecuta el mismo trabajo en 8 vCPU a $0.008 por minuto; consulte precios.

Ejecute esta compilación de Go en compiler.dev Sin tarjeta · 200 minutos gratuitos

Pruébelo gratis