Saltar al contenido

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/cache en 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 --immutable falla si el lockfile fuera a cambiar, que es lo que se busca en CI. Berry también incluye --immutable-cache para 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ónCachear estoComando de instalación
Classic 1.xyarn cache diryarn install --frozen-lockfile
Berry, caché globalyarn config get cacheFolderyarn install --immutable
Berry, zero-installnada (confirmado en el repositorio)yarn install --immutable --immutable-cache

Cómo verificar un acierto de caché

  1. El registro del paso de restauración muestra Cache restored from key: ... en un acierto y Cache not found for input keys: ... en un fallo.
  2. 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.
  3. En Classic, una instalación con caché caliente depende sobre todo de la fase de enlace; la fase de descarga es breve.
  4. gh cache list --key yarn- --limit 20 confirma qué se guardó y cuándo se usó por última vez.

Errores comunes

  1. Calcular el hash del archivo equivocado. package.json cambia con más frecuencia que yarn.lock e invalida la caché innecesariamente. Calcule el hash del lockfile.
  2. 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.
  3. Una sola clave para Classic y Berry. Si migra, cambie el prefijo de la clave para que no se restaure el formato antiguo.
  4. 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.
  5. 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é.

Ejecute este workflow en compiler.dev Sin tarjeta · 200 minutos gratuitos

Pruébelo gratis