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 ci | Notas |
|---|---|---|
~/.npm | Sí | Pequeña y segura entre versiones de Node |
node_modules | No | Se borra al instalar; los módulos nativos fallan entre versiones de Node |
.next/cache, .vite, .eslintcache | Sí, por separado | Caché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é
- Abra el paso de setup-node o de cache en el registro del job. Un acierto muestra
Cache restored from key: .... Un fallo muestraCache not found for input keys: .... - Con
actions/cache, la salidacache-hitvale'true'solo si la clave coincide exactamente. Una coincidencia parcial conrestore-keysdevuelve'false'aunque se hayan restaurado archivos. - Al final de un fallo, busque
Cache saved with key: ...en el paso posterior. - 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
- Usar
npm installen lugar denpm ci.npm installpuede reescribir el lockfile, de modo que su clave y el árbol instalado dejan de coincidir. - Un lockfile que no está confirmado en el repositorio.
hashFilesdevuelve 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. - Versiones principales de Node que comparten una clave. Añada la versión a la clave si usa una matriz.
- 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
mainejecuten el mismo paso de caché para que cada PR pueda leer una caché cargada. - 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.
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.
- Caché de dependencias de pip en GitHub ActionsCachee pip en GitHub Actions con setup-python o actions/cache, además de la opción más rápida uv. Claves, qué no cachear y cómo verificar un acierto.