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 registraCache restored from key: .... - Mida
pnpm install. Con un store caliente, la línea de progreso de pnpm indica los paquetes comoreuseden lugar dedownloaded. gh cache list --key pnpm- --limit 20muestra 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
- Orden de los pasos.
actions/setup-nodeantes depnpm/action-setupfalla concache: pnpm. - 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.
- Usar
pnpm installsin--frozen-lockfile. Sea explícito en CI para que un lockfile desactualizado haga fallar la compilación en lugar de resolver silenciosamente versiones nuevas. - 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. - 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).
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.