Caché de dependencias de Yarn en GitHub Actions
Última actualización
Para cachear Yarn en GitHub Actions, configure cache: yarn en actions/setup-node e instale con un lockfile congelado. El detalle es que Yarn Classic (1.x) y Yarn Berry (2+) almacenan los paquetes en lugares distintos y usan opciones diferentes, por lo que la receta explícita cambia en cada caso.
Primero compruebe cuál tiene: yarn --version muestra 1.22.x para Classic y 3.x o 4.x para Berry.
Opción 1: caché integrada de setup-node
jobs:
test:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v6
- run: corepack enable # needed for Berry and packageManager pinning
- uses: actions/setup-node@v7
with:
node-version: 22
cache: yarn
- run: yarn install --immutable # Berry
# Classic: yarn install --frozen-lockfile
- run: yarn test
Según el README de setup-node (revisado en octubre de 2026), cache: yarn calcula el hash de yarn.lock por defecto, y el gestor de paquetes debe estar ya instalado. Ejecutar corepack enable antes de setup-node hace disponible la versión de Yarn indicada en packageManager de package.json. Si hay varios lockfiles, use cache-dependency-path.
Opción 2: actions/cache explícito para Classic
Classic mantiene una caché global. Consulte dónde está:
- uses: actions/setup-node@v7
with:
node-version: 22
- name: Get Yarn cache dir
id: yarn-cache
run: echo "dir=$(yarn cache dir)" >> "$GITHUB_OUTPUT"
- uses: actions/cache@v6
with:
path: ${{ steps.yarn-cache.outputs.dir }}
key: yarn-classic-${{ runner.os }}-${{ hashFiles('**/yarn.lock') }}
restore-keys: |
yarn-classic-${{ runner.os }}-
- run: yarn install --frozen-lockfile
Opción 3: actions/cache explícito para Berry
La ubicación de la caché de Berry depende de enableGlobalCache en .yarnrc.yml. Lea la configuración real en lugar de suponerla:
- run: corepack enable
- uses: actions/setup-node@v7
with:
node-version: 22
- name: Get Yarn cache folder
id: yarn-cache
run: echo "dir=$(yarn config get cacheFolder)" >> "$GITHUB_OUTPUT"
- uses: actions/cache@v6
with:
path: ${{ steps.yarn-cache.outputs.dir }}
key: yarn-berry-${{ runner.os }}-${{ hashFiles('**/yarn.lock') }}
restore-keys: |
yarn-berry-${{ runner.os }}-
- run: yarn install --immutable
Si su repositorio usa nodeLinker: node-modules, la instalación sigue leyendo de esta carpeta de caché y después escribe node_modules. Si usa Plug'n'Play (el valor por defecto), no hay node_modules: Yarn escribe .pnp.cjs y lee los archivos zip directamente.
Particularidades de Berry que conviene conocer
- Zero-install. Si incluye
.yarn/cacheen git, el checkout ya contiene los paquetes. No hay nada que cachear; añadir un paso de caché solo aporta sobrecarga. La contrapartida es un repositorio de gran tamaño. - Instalaciones inmutables.
yarn install --immutablefalla si el lockfile fuera a cambiar, que es lo que se busca en CI. Berry también incluye--immutable-cachepara fallar si la caché cambiaría. - Claves de caché. Incluya
runner.os. Los archivos de caché de Berry pueden contener compilaciones específicas de cada plataforma para paquetes con enlaces nativos.
¿Por qué no node_modules?
Por la misma razón que en la guía de npm: una instalación nueva lo reescribe, y los módulos nativos compilados para una versión de Node fallan con otra. La caché de paquetes es la parte que se puede reutilizar con seguridad y cuya restauración cuesta menos.
| Configuración | Cachear esto | Comando de instalación |
|---|---|---|
| Classic 1.x | yarn cache dir | yarn install --frozen-lockfile |
| Berry, caché global | yarn config get cacheFolder | yarn install --immutable |
| Berry, zero-install | nada (confirmado en el repositorio) | yarn install --immutable --immutable-cache |
Cómo verificar un acierto de caché
- El registro del paso de restauración muestra
Cache restored from key: ...en un acierto yCache not found for input keys: ...en un fallo. - En Berry, la salida de la instalación muestra los pasos de resolución, descarga y enlace con sus tiempos. Con una caché caliente, el paso de descarga es casi instantáneo; con una fría, aparecen los paquetes que se descargan.
- En Classic, una instalación con caché caliente depende sobre todo de la fase de enlace; la fase de descarga es breve.
gh cache list --key yarn- --limit 20confirma qué se guardó y cuándo se usó por última vez.
Errores comunes
- Calcular el hash del archivo equivocado.
package.jsoncambia con más frecuencia queyarn.locke invalida la caché innecesariamente. Calcule el hash del lockfile. - No activar Corepack. El paso de caché de setup-node ejecuta
yarn; si responde un Yarn global incorrecto, el directorio de caché que informa es erróneo. - Una sola clave para Classic y Berry. Si migra, cambie el prefijo de la clave para que no se restaure el formato antiguo.
- Cachear solo en PR. Al limitarse a la rama, las cachés de los PR no se comparten. Ejecútelo también en
main. Consulte Caché en GitHub Actions. - Ignorar el tamaño. Las cachés de Berry contienen archivos zip y pueden alcanzar varios GB en monorepos grandes. Vigile el límite de 10 GB.
Preguntas frecuentes
¿Admite setup-node la caché de Yarn Berry?
Sí, con cache: yarn. Asegúrese de que Corepack haya activado la versión correcta de Yarn antes del paso de configuración.
¿Debo incluir .yarn/cache en git (zero-install)?
Elimina el paso de caché y el tiempo de red de la instalación, a costa del tamaño del repositorio y de diffs más ruidosos. Es una preferencia del equipo, no un requisito de CI.
¿Por qué falla yarn install --immutable en CI?
El lockfile de la rama no está sincronizado con package.json. Ejecute yarn install en local y haga commit de yarn.lock.
¿Es diferente la caché de Yarn en un monorepo?
Los workspaces comparten un único lockfile y una única carpeta de caché, así que la receta es idéntica. Use cache-dependency-path si tiene más de un lockfile.
Próximos pasos
Consulte los equivalentes para pnpm y npm, y cómo acelerar GitHub Actions para ver qué probar después de la caché. Para saber cuánto ahorra una mejor tasa de aciertos, use el estimador de ahorro de caché.
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.
- 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.