Saltar al contenido

Caché de dependencias de pnpm en GitHub Actions

Última actualización

Para cachear pnpm en GitHub Actions, instale primero pnpm y, a continuación, defina cache: pnpm en actions/setup-node. Así se cachea el almacén direccionable por contenido de pnpm, con la clave basada en pnpm-lock.yaml. El orden importa: setup-node necesita que pnpm exista antes de ejecutarse, por lo que pnpm/action-setup debe ir antes.

Opción 1: caché de setup-node

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v6
      - uses: pnpm/action-setup@v6
      - uses: actions/setup-node@v7
        with:
          node-version: 22
          cache: pnpm
      - run: pnpm install --frozen-lockfile
      - run: pnpm test

pnpm/action-setup puede omitir version cuando package.json incluye el campo packageManager (por ejemplo, "packageManager": "pnpm@10.9.0"). Es la configuración más limpia: un único lugar define la versión de pnpm para su portátil y para CI. En caso contrario, pase with: { version: 10 }.

El README de setup-node (revisado en octubre de 2026) indica que el valor de caché pnpm requiere pnpm 6.10 o posterior y que pnpm debe estar instalado previamente. Si ve Unable to locate executable file: pnpm, el orden de los pasos es incorrecto.

Opción 2: dejar que pnpm/action-setup cachee el store

pnpm/action-setup tiene su propia entrada cache, desactivada por defecto. Su README la describe como el caché del directorio del store de pnpm, con la clave derivada de pnpm-lock.yaml (puede cambiarla con cache_dependency_path).

- uses: pnpm/action-setup@v6
  with:
    cache: true
- uses: actions/setup-node@v7
  with:
    node-version: 22
- run: pnpm install --frozen-lockfile

Elija un mecanismo, no ambos. Dos cachés del mismo store desperdician cuota.

Opción 3: actions/cache explícito

Pregunte a pnpm dónde está el store en lugar de suponerlo. La ubicación varía según el sistema operativo y la versión de pnpm.

- uses: pnpm/action-setup@v6
- uses: actions/setup-node@v7
  with:
    node-version: 22
- name: Get pnpm store path
  id: pnpm-store
  run: echo "path=$(pnpm store path --silent)" >> "$GITHUB_OUTPUT"
- uses: actions/cache@v6
  with:
    path: ${{ steps.pnpm-store.outputs.path }}
    key: pnpm-${{ runner.os }}-${{ hashFiles('**/pnpm-lock.yaml') }}
    restore-keys: |
      pnpm-${{ runner.os }}-
- run: pnpm install --frozen-lockfile

El patrón hashFiles('**/pnpm-lock.yaml') gestiona repositorios con más de un lockfile. En un workspace estándar de pnpm hay un único lockfile en la raíz, así que el hash es estable y solo cambia cuando cambian las dependencias.

Qué cachear y qué no

pnpm guarda cada paquete una sola vez en el store y crea enlaces duros (o copias) de los archivos en el node_modules de cada proyecto. Este diseño es el motivo por el que basta con cachear el store.

  • Cachee el store. Es la parte costosa: las descargas de red.
  • No cachee node_modules. Es un árbol de enlaces al store. Al restaurarlo desde un tarball se convierte en copias completas, puede ser enorme y puede no coincidir con la estructura del store en la siguiente ejecución.
  • No codifique la ruta del store. Use pnpm store path.

Una advertencia: los enlaces duros solo funcionan dentro de un mismo sistema de archivos. Si el store se restaura en un volumen distinto al de su workspace, pnpm recurre a copiar, que es más lento pero sigue siendo correcto.

Workspaces

Para un workspace, instale una vez en la raíz y ejecute las tareas con filtros:

- run: pnpm install --frozen-lockfile
- run: pnpm --filter "...[origin/main]" test

Para que el filtro funcione, el checkout necesita suficiente historial. Consulte CI más rápido para workspaces de pnpm para la configuración completa, incluido fetch-depth.

Cómo verificar un acierto de caché

  • El paso posterior de setup-node registra Cache saved with key: ... cuando no hay acierto. Si lo hay, el paso de restauración registra Cache restored from key: ....
  • Mida pnpm install. Con un store caliente, la línea de progreso de pnpm indica los paquetes como reused en lugar de downloaded.
  • gh cache list --key pnpm- --limit 20 muestra las entradas, sus tamaños y las fechas del último acceso.

Un ejemplo completo con matrix

Las cachés se indexan por sistema operativo, así que una matrix sobre versiones de Node genera una entrada por combinación, salvo que comparta el store. El store de pnpm es en gran medida independiente de la versión de Node, por lo que una clave sin la versión de Node suele bastar y ahorra cuota:

jobs:
  test:
    runs-on: ubuntu-latest
    strategy:
      fail-fast: false
      matrix:
        node: [20, 22]
    steps:
      - uses: actions/checkout@v6
      - uses: pnpm/action-setup@v6
      - uses: actions/setup-node@v7
        with:
          node-version: ${{ matrix.node }}
          cache: pnpm
      - run: pnpm install --frozen-lockfile
      - run: pnpm test

setup-node construye su clave a partir del sistema operativo, el gestor de paquetes y el hash del lockfile, por lo que ambas combinaciones de la matrix restauran la misma entrada del store. Los paquetes con complementos nativos se recompilan por versión de Node durante la instalación, pero sus descargas siguen procediendo de la caché. Consulte la calculadora de ahorro de caché para ver cuánto vale la tasa de aciertos según el número de ejecuciones.

Errores comunes

  1. Orden de los pasos. actions/setup-node antes de pnpm/action-setup falla con cache: pnpm.
  2. Versiones de pnpm incompatibles. La estructura del store cambia entre versiones principales. Incluya la versión mayor de pnpm en su clave si actualiza con frecuencia.
  3. Usar pnpm install sin --frozen-lockfile. Sea explícito en CI para que un lockfile desactualizado haga fallar la compilación en lugar de resolver silenciosamente versiones nuevas.
  4. Escribir la caché solo en pull requests. Las cachés de los PR están asociadas a la referencia de fusión del PR. Rellénela también desde main. Detalles en Caché en GitHub Actions.
  5. Olvidar el límite de 10 GB. Cada combinación de sistema operativo y Node crea una entrada nueva. Consulte los límites de caché.

Preguntas frecuentes

¿Dónde está el store de pnpm en un runner alojado por GitHub?

Ejecute pnpm store path en un paso para mostrarlo. Depende del sistema operativo y de la versión de pnpm, por eso la receta explícita lo lee dinámicamente.

¿Es pnpm más rápido que npm en CI?

A menudo, con un store caliente, porque enlaza archivos en lugar de copiarlos. La ganancia depende de su árbol de dependencias; mida ambos con el mismo estado de caché.

¿Debo incluir el store de pnpm en el commit?

No. Una caché es el lugar adecuado para él.

¿Qué pasa con las cachés de Turborepo o Nx?

Esas cachean las salidas de las tareas, no las dependencias. Consulte CI de monorepos con Nx o Turborepo.

Próximos pasos

Compare con las configuraciones de npm y Yarn. Si las instalaciones son rápidas y el job sigue siendo lento, el cuello de botella es la CPU; compiler.dev ejecuta el mismo workflow en máquinas de 8 vCPU a $0.008 por minuto (consulte precios).

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

Pruébelo gratis