Cachear Cargo y compilaciones de Rust en GitHub Actions
Última actualización
Para cachear Cargo en GitHub Actions, la opción más sencilla es Swatinem/rust-cache. Guarda en caché el registro de Cargo, las dependencias de git y las dependencias compiladas en target, y depura la caché antes de guardarla. La forma explícita con actions/cache también funciona, pero cachear target sin criterio acaba siendo enorme y lenta.
Opción 1: Swatinem/rust-cache
jobs:
test:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v6
- uses: dtolnay/rust-toolchain@stable
- uses: Swatinem/rust-cache@v2
- run: cargo test --locked
Según el README de rust-cache (consultado en octubre de 2026), la acción guarda en caché ~/.cargo (binarios instalados, el índice del registro y la caché de crates, y las dependencias de git, excluyendo registry/src) y ./target. No guarda en caché los crates de su propio espacio de trabajo, solo sus dependencias. La clave se construye a partir del nombre del job, la versión de Rust y el hash de Cargo.lock y de los archivos de manifiesto, y establece CARGO_INCREMENTAL=0.
Antes de guardar, elimina todo lo que no sea una dependencia actual, los artefactos incrementales y los artefactos de compilación con más de una semana. Esa limpieza es el principal motivo para preferirla a una caché escrita a mano.
Entradas que realmente utilizará:
- uses: Swatinem/rust-cache@v2
with:
workspaces: |
. -> target
tools/xtask -> target
shared-key: ci
save-if: ${{ github.ref == 'refs/heads/main' }}
cache-on-failure: true
workspacesenumera paresworkspace -> targetpara repositorios con más de un workspace de Cargo.shared-keyhace que varios jobs compartan una misma caché en lugar de una por nombre de job. Resulta útil cuandocheck,clippyytestcompilan las mismas dependencias, aunque los perfiles debug y release difieren, así que compártala solo entre jobs con el mismo perfil.save-ifguarda solo desdemain, para que las ramas de PR no consuman su cuota.cache-on-failureguarda la caché aunque el job falle, lo que resulta útil porque una ejecución de tests fallida ya ha compilado todas las dependencias.
Opción 2: actions/cache explícito
- uses: actions/cache@v6
with:
path: |
~/.cargo/registry/index/
~/.cargo/registry/cache/
~/.cargo/git/db/
target/
key: cargo-${{ runner.os }}-${{ runner.arch }}-${{ hashFiles('**/Cargo.lock') }}
restore-keys: |
cargo-${{ runner.os }}-${{ runner.arch }}-
- run: cargo build --locked
Este es el patrón que recomiendan la documentación de Cargo y los ejemplos de actions/cache. La clave incluye el SO, la arquitectura y Cargo.lock. Añada la versión del compilador (rustc --version) si no fija la toolchain con rust-toolchain.toml, ya que los artefactos generados por un rustc no se reutilizan con otro.
Qué cachear y qué no
| Ruta | ¿Cachear? | Motivo |
|---|---|---|
~/.cargo/registry/index y registry/cache | Sí | Evita volver a descargar crates |
~/.cargo/git/db | Sí | Dependencias de git |
~/.cargo/registry/src | No | Fuentes descomprimidas; Cargo las recrea rápidamente desde cache |
Dependencias en target/ | Sí | La gran ventaja: los crates de dependencias ya compilados |
target/ de sus propios crates | No | Cambia en cada commit e infla la caché |
target/**/incremental | No | Voluminoso y rara vez útil en CI |
~/.cargo/bin | Con cuidado | Cachee las herramientas instaladas por versión, no en bloque |
La trampa de la «caché rodante»: con una clave explícita basada en Cargo.lock, la caché solo se guarda cuando cambia el lockfile. Los crates de su workspace nunca se guardan, que es lo que se busca. Si en cambio usa github.sha como clave, la caché crece con la salida de compilación de cada commit. rust-cache evita esto limpiando antes de guardar.
Cuando target es demasiado grande
El directorio target de Rust para un workspace grande puede ocupar varios GB, y el tiempo de restauración crece con él. Opciones:
- Desactive la información de depuración en CI:
CARGO_PROFILE_DEV_DEBUG=0(odebug = "line-tables-only"). Reduce los artefactos y acelera el enlazado. - Use
sccachecomo envoltorio del compilador con el backend de caché de GitHub Actions en lugar de cacheartarget. Guarda resultados de compilación por crate en lugar de directorios completos. - Cachee solo
~/.cargoy acepte recompilar las dependencias. A menudo es peor, pero consume menos cuota. - Ejecute en más núcleos. El tiempo de compilación escala con la CPU; consulte runners más rápidos. En la prueba medida de compiler.dev con React más Rust (Axum) y Postgres, el CI completo pasó de 2m37s a 1m45s (consulte benchmarks).
Otras mejoras de velocidad que importan más que la caché
cargo test --lockedfalla siCargo.lockno está actualizado, de modo que la CI nunca resuelve dependencias en silencio.cargo nextestejecuta las pruebas en paralelo entre binarios; combínelo con sharding de pruebas para suites grandes.- Use
cargo checken los jobs que solo hacen lint. Omite la generación de código. moldolldcomo enlazador reducen el tiempo de enlazado de binarios grandes.
Cómo verificar un acierto de caché
- rust-cache registra
Cache restored from key: ...(busqueRestoring cachey la clave que coincidió) y, en el paso posterior, un resumen de lo que guardó o de por qué no lo hizo. - En la salida de la compilación, una ejecución con caché caliente muestra
Compilingsolo para sus propios crates. Una ejecución en frío lista todas las dependencias. - Compare el tiempo de
cargo buildentre ejecuciones con el mismo lockfile. gh cache list --key rust --limit 20muestra el tamaño y la última vez que se usó.
Errores comunes
- Varios jobs compartiendo una misma clave. Las compilaciones debug y release, o
clippyytest, se invalidan entre sí. Use claves por perfil. - No usar
--locked. Un lockfile que cambia en silencio altera el significado de la clave. - Guardar todo el
targetdesde cada PR. Las cachés de los PR no se comparten entre PR; guarde desdemain. Consulte Caching in GitHub Actions. - Alcanzar la cuota. Las cachés de Rust son grandes. Lea los límites de caché.
Preguntas frecuentes
¿Debo cachear el directorio target?
Sí, cachee los artefactos de las dependencias y deje que una herramienta como rust-cache elimine la salida de sus propios crates. Cachear todo crece sin límite.
¿Es sccache mejor que rust-cache?
Resuelven problemas distintos. rust-cache restaura un directorio; sccache guarda en caché unidades de compilación individuales y funciona entre ramas y perfiles. En workspaces grandes sccache puede ser mejor; para la mayoría de proyectos rust-cache es más sencillo.
¿Por qué importa CARGO_INCREMENTAL=0?
La compilación incremental genera artefactos grandes que ayudan a las recompilaciones locales, pero sirven de poco en una máquina de CI nueva.
¿Cómo cacheo las herramientas de cargo install?
Use como clave la herramienta y su versión, o use una action de binarios precompilados como taiki-e/install-action.
Próximos pasos
Lectura relacionada: cómo acelerar la CI de Rust de principio a fin, caché de módulos de Go para un patrón similar de dos directorios, y cómo acelerar GitHub Actions. Para probar la CI de Rust en máquinas de 8 vCPU, consulte precios de compiler.dev.
Relacionado
- Caché de módulos Go y de compilación en GitHub ActionsCachee los módulos Go (GOMODCACHE) y la caché de compilación (GOCACHE) en GitHub Actions con setup-go o actions/cache. Claves, go.sum y aciertos.
- 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.