Saltar al contenido

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
  • workspaces enumera pares workspace -> target para repositorios con más de un workspace de Cargo.
  • shared-key hace que varios jobs compartan una misma caché en lugar de una por nombre de job. Resulta útil cuando check, clippy y test compilan las mismas dependencias, aunque los perfiles debug y release difieren, así que compártala solo entre jobs con el mismo perfil.
  • save-if guarda solo desde main, para que las ramas de PR no consuman su cuota.
  • cache-on-failure guarda 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/cacheSíEvita volver a descargar crates
~/.cargo/git/dbSíDependencias de git
~/.cargo/registry/srcNoFuentes 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 cratesNoCambia en cada commit e infla la caché
target/**/incrementalNoVoluminoso y rara vez útil en CI
~/.cargo/binCon cuidadoCachee 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:

  1. Desactive la información de depuración en CI: CARGO_PROFILE_DEV_DEBUG=0 (o debug = "line-tables-only"). Reduce los artefactos y acelera el enlazado.
  2. Use sccache como envoltorio del compilador con el backend de caché de GitHub Actions en lugar de cachear target. Guarda resultados de compilación por crate en lugar de directorios completos.
  3. Cachee solo ~/.cargo y acepte recompilar las dependencias. A menudo es peor, pero consume menos cuota.
  4. 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 --locked falla si Cargo.lock no está actualizado, de modo que la CI nunca resuelve dependencias en silencio.
  • cargo nextest ejecuta las pruebas en paralelo entre binarios; combínelo con sharding de pruebas para suites grandes.
  • Use cargo check en los jobs que solo hacen lint. Omite la generación de código.
  • mold o lld como enlazador reducen el tiempo de enlazado de binarios grandes.

Cómo verificar un acierto de caché

  1. rust-cache registra Cache restored from key: ... (busque Restoring cache y la clave que coincidió) y, en el paso posterior, un resumen de lo que guardó o de por qué no lo hizo.
  2. En la salida de la compilación, una ejecución con caché caliente muestra Compiling solo para sus propios crates. Una ejecución en frío lista todas las dependencias.
  3. Compare el tiempo de cargo build entre ejecuciones con el mismo lockfile.
  4. gh cache list --key rust --limit 20 muestra el tamaño y la última vez que se usó.

Errores comunes

  1. Varios jobs compartiendo una misma clave. Las compilaciones debug y release, o clippy y test, se invalidan entre sí. Use claves por perfil.
  2. No usar --locked. Un lockfile que cambia en silencio altera el significado de la clave.
  3. Guardar todo el target desde cada PR. Las cachés de los PR no se comparten entre PR; guarde desde main. Consulte Caching in GitHub Actions.
  4. 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.

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

Pruébelo gratis