Saltar al contenido

Cachear dependencias de npm en GitHub Actions

Última actualización

Para cachear las dependencias de npm en GitHub Actions, añada cache: npm a actions/setup-node e instale con npm ci. Así se cachea el directorio de descargas de npm (~/.npm), usando como clave su package-lock.json. Si necesita controlar la clave o la ruta, la forma explícita con actions/cache que se muestra más abajo hace lo mismo.

Esta página es la receta específica para npm. Para saber cómo funcionan en general las claves, el alcance y restore-keys, lea primero Caching en GitHub Actions.

Opción 1: caché integrada de setup-node

name: CI
on: [push, pull_request]

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v6
      - uses: actions/setup-node@v7
        with:
          node-version: 22
          cache: npm
      - run: npm ci
      - run: npm test

La acción calcula el hash de package-lock.json (o npm-shrinkwrap.json) en la raíz del repositorio para construir la clave. En un monorepo o cuando el lockfile no está en la raíz, indique el archivo correcto:

- uses: actions/setup-node@v7
  with:
    node-version: 22
    cache: npm
    cache-dependency-path: |
      package-lock.json
      apps/web/package-lock.json

cache-dependency-path solo tiene efecto cuando cache está definido. Según el README de setup-node (revisado en octubre de 2026), la caché de npm también puede activarse automáticamente si package.json declara npm en el campo packageManager, y puede desactivarlo con package-manager-cache: false. Definir cache: npm explícitamente hace que el comportamiento sea más claro.

Opción 2: actions/cache explícito

Use esta opción si quiere una clave personalizada, restaurar y guardar por separado, o si no usa setup-node.

- uses: actions/setup-node@v7
  with:
    node-version: 22
- name: Get npm cache directory
  id: npm-cache
  run: echo "dir=$(npm config get cache)" >> "$GITHUB_OUTPUT"
- uses: actions/cache@v6
  with:
    path: ${{ steps.npm-cache.outputs.dir }}
    key: npm-${{ runner.os }}-node22-${{ hashFiles('**/package-lock.json') }}
    restore-keys: |
      npm-${{ runner.os }}-node22-
- run: npm ci

Pedir a npm su directorio de caché evita escribir ~/.npm de forma fija, lo que no funciona en los runners de Windows. La clave incluye el sistema operativo, la versión principal de Node y el hash del lockfile. La línea restore-keys significa que un cambio de un solo paquete sigue restaurando la mayor parte de la caché del día anterior, así que npm ci solo descarga la diferencia.

Cachee ~/.npm, no node_modules

El consejo habitual de cachear node_modules sale contraproducente con npm. npm ci borra node_modules antes de instalar, así que una copia restaurada se descarta. Se paga la descarga y extracción de esa copia y después se paga de nuevo para reconstruirla.

Cachear ~/.npm es diferente. npm ci sigue descomprimiendo todos los paquetes, pero lee los tarballs desde el disco local en lugar de hacerlo desde el registro. Ahí es donde se va el tiempo de red.

CachéFunciona con npm ciNotas
~/.npmSíPequeña y segura entre versiones de Node
node_modulesNoSe borra al instalar; los módulos nativos fallan entre versiones de Node
.next/cache, .vite, .eslintcacheSí, por separadoCachés de build y lint, no de dependencias

Si el tiempo de instalación sigue siendo un problema tras cachear, el paso de descompresión está limitado por la CPU y el disco. Es un problema de la máquina, no de la caché.

Cómo verificar un acierto de caché

  1. Abra el paso de setup-node o de cache en el registro del job. Un acierto muestra Cache restored from key: .... Un fallo muestra Cache not found for input keys: ....
  2. Con actions/cache, la salida cache-hit vale 'true' solo si la clave coincide exactamente. Una coincidencia parcial con restore-keys devuelve 'false' aunque se hayan restaurado archivos.
  3. Al final de un fallo, busque Cache saved with key: ... en el paso posterior.
  4. Liste lo que existe con la CLI:
gh cache list --key npm- --limit 20

Ejecute el workflow dos veces con el mismo lockfile. La segunda ejecución debería indicar que se restauró, y el paso de instalación debería reducirse notablemente.

Errores comunes

  1. Usar npm install en lugar de npm ci. npm install puede reescribir el lockfile, de modo que su clave y el árbol instalado dejan de coincidir.
  2. Un lockfile que no está confirmado en el repositorio. hashFiles devuelve una cadena vacía, todas las ejecuciones usan la misma clave y la caché nunca se actualiza. En este caso setup-node falla con un error, lo que resulta útil.
  3. Versiones principales de Node que comparten una clave. Añada la versión a la clave si usa una matriz.
  4. Cachés creadas solo en pull requests. Las cachés de PR están limitadas a la referencia de fusión y no son visibles para otros PR. Asegúrese de que los push a main ejecuten el mismo paso de caché para que cada PR pueda leer una caché cargada.
  5. Binarios de postinstall. Paquetes como Playwright, Cypress y Puppeteer descargan navegadores fuera de ~/.npm. Cachee esos directorios por separado; consulte Tests de Playwright lentos y Tests de Cypress lentos.

Tamaño y expulsión

Una caché típica de npm ocupa unos cientos de MB. El límite del repositorio es de 10 GB, y las entradas antiguas se expulsan primero las menos usadas recientemente, eliminándose cualquiera sin uso durante 7 días. Una matriz sobre varias versiones de Node y sistemas operativos multiplica las entradas rápidamente. Consulte límites y expulsión de cachés para ver qué está consumiendo su cuota.

El estimador de ahorro por aciertos de caché muestra cuántos minutos supone una mejor tasa de aciertos.

Preguntas frecuentes

¿Debo usar npm ci o npm install en CI?

Use npm ci. Instala exactamente lo que indica el lockfile, falla si package.json y el lockfile no coinciden, y es más rápido en instalaciones limpias.

¿Funciona la caché de setup-node en pull requests desde forks?

Restaura las cachés que creó la rama base. Los guardados desde PR de forks están limitados por los permisos del token de GitHub, así que confíe en main para llenar la caché.

¿Por qué mi caché de npm se restaura pero npm ci sigue siendo lento?

La caché elimina las descargas, no la extracción ni los scripts del ciclo de vida. Revise el tiempo dedicado a los scripts postinstall, o pruebe un runner más rápido.

¿Puedo compartir la caché de npm entre distintos workflows?

Sí. Las cachés pertenecen al repositorio. Misma clave y misma ruta, misma caché.

Próximos pasos

Si también usa pnpm o Yarn, consulte caché de pnpm y caché de Yarn. Para la lista completa de soluciones, lea cómo acelerar GitHub Actions. compiler.dev ejecuta sus jobs en máquinas de 8 vCPU con una caché de dependencias lista; consulte precios.

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

Pruébelo gratis