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é | Contenido | Ahorra | Clave |
|---|---|---|---|
GOMODCACHE | Código fuente de módulos descargados | Tiempo de red | go.sum |
GOCACHE | Paquetes compilados, resultados de pruebas | Tiempo de compilación y de pruebas | go.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 downloadcomo paso independiente hace visible en los registros el tiempo dedicado a las dependencias.go test -racees 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 congo 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. -pcontrola 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é
- El paso de setup-go registra
Cache restored from key: setup-go-Linux-...cuando encuentra la caché, yCache not foundcuando no la encuentra. Su paso posterior registraCache saved. - Ejecute
go build -xen local o en un trabajo de depuración: los paquetes restaurados no se recompilan.go testmuestra(cached)en los paquetes sin cambios. go mod downloaddebería terminar en menos de un segundo cuandoGOMODCACHEestá caliente.gh cache list --key setup-go --limit 20muestra el tamaño y el último uso.
Errores comunes
- Calcular el hash de
go.modcuando el grafo de módulos está engo.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. - Un repositorio con vendor y caché. Si
go mod vendorestá confirmado, no hay descarga de módulos que almacenar en caché. Almacene en caché soloGOCACHE. - Almacenar en caché
GOPATH/bin. Las herramientas instaladas congo installdeben tener como clave la versión de la herramienta. - 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.
- 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.
Relacionado
- Cachear Cargo y compilaciones de Rust en GitHub ActionsCachee el registro de Cargo, las dependencias git y el directorio target en GitHub Actions con Swatinem/rust-cache o actions/cache, sin cachés inflados.
- Cachear compilaciones de Gradle en GitHub ActionsCachee las dependencias y la caché de compilación de Gradle en GitHub Actions con gradle/actions/setup-gradle o actions/cache. Claves, PR de solo lectura.
- Cachear dependencias de npm en GitHub ActionsAlmacene en caché las dependencias de npm en GitHub Actions con setup-node o actions/cache. YAML funcional, la clave correcta y por qué no node_modules.
- Caché de dependencias de pip en GitHub ActionsCachee pip en GitHub Actions con setup-python o actions/cache, además de la opción más rápida uv. Claves, qué no cachear y cómo verificar un acierto.