Saltar al contenido

Acelere Next.js en GitHub Actions

Última actualización

La forma más rápida de acelerar Next.js en GitHub Actions es conservar .next/cache entre ejecuciones y dejar de instalar y compilar las mismas cosas en cada job. Un next build en frío recompila y reoptimiza todo. Uno en caliente reutiliza las cachés del compilador y de imágenes y solo procesa los archivos que han cambiado.

Esta guía cubre los costes reales de un pipeline de Next.js: instalación, compilación, comprobación de tipos, tests unitarios y tests end-to-end. Es la versión para Next.js de nuestra guía general para acelerar GitHub Actions.

Dónde se va el tiempo

Un workflow típico de Next.js realiza cinco tareas: instalar dependencias, lint, comprobación de tipos, compilación y tests. En un runner de 2 vCPU, la compilación suele ser el paso más largo, y next build le avisa cuando es lenta por un motivo solucionable: "No Cache Detected". Ese mensaje indica que .next/cache estaba vacía. Next.js lo documenta en su guía de caché de compilación para CI.

Revise primero los tiempos de cada paso. Si la instalación tarda 60 segundos y la compilación tres minutos, solucione antes la caché de compilación.

Cachear .next/cache y el gestor de paquetes

Next.js guarda la salida de su compilador y de optimización en .next/cache. La guía oficial muestra una clave construida a partir del hash del lockfile más un hash de los archivos fuente, con un restore-keys como alternativa. Esa alternativa es importante: al cambiar un archivo fuente, la clave exacta no coincide, pero la clave de restauración recupera la caché anterior, de modo que solo se recompilan los archivos modificados.

name: ci
on:
  pull_request:
  push:
    branches: [main]

concurrency:
  group: ci-${{ github.ref }}
  cancel-in-progress: ${{ github.ref != 'refs/heads/main' }}

jobs:
  build:
    runs-on: ubuntu-latest
    timeout-minutes: 20
    steps:
      - uses: actions/checkout@v7
      - uses: actions/setup-node@v7
        with:
          node-version: 24
          cache: npm
      - uses: actions/cache@v6
        with:
          path: ${{ github.workspace }}/.next/cache
          key: ${{ runner.os }}-nextjs-${{ hashFiles('**/package-lock.json') }}-${{ hashFiles('**/*.js', '**/*.jsx', '**/*.ts', '**/*.tsx') }}
          restore-keys: |
            ${{ runner.os }}-nextjs-${{ hashFiles('**/package-lock.json') }}-
      - run: npm ci
      - run: npm run build

Hay dos detalles. Primero, actions/setup-node con cache: npm cachea la caché de descargas de npm, no node_modules, así que npm ci sigue haciendo una instalación limpia, pero sin descargas. Use cache: pnpm o cache: yarn para esos gestores. Segundo, las entradas de caché de GitHub son inmutables: una ejecución solo puede guardar una clave que aún no existe. Una clave que incluye el hash del código fuente crea una entrada nueva en casi cada PR, lo que consume su cuota. Consulte los límites de caché de GitHub Actions para las reglas de expulsión, y use el generador de claves de caché para probar otras claves.

Divida el trabajo en jobs paralelos

El lint, la comprobación de tipos y los tests unitarios no necesitan la salida de la compilación. Ejecútelos como jobs separados para que se solapen con la compilación:

  lint:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v7
      - uses: actions/setup-node@v7
        with:
          node-version: 24
          cache: npm
      - run: npm ci
      - run: npx eslint . --cache --cache-location .eslintcache
      - run: npx tsc --noEmit --incremental
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v7
      - uses: actions/setup-node@v7
        with:
          node-version: 24
          cache: npm
      - run: npm ci
      - run: npx vitest run

Cada job repite el checkout y la instalación, así que esto solo compensa mientras la instalación esté cacheada y sea corta. Si sus tests unitarios son la parte lenta, consulte Jest lento o Vitest lento.

Turbopack y el tiempo de compilación

Las versiones recientes de Next.js usan Turbopack, un bundler escrito en Rust, para next dev y next build. Consulte las notas de la versión que usa para saber si next build lo utiliza por defecto y qué flags activan o desactivan su uso, ya que esto ha cambiado entre versiones. Turbopack es multihilo, así que se beneficia de más núcleos que los 2 de un runner alojado por defecto. No elimina la necesidad de .next/cache. Mida next build con y sin él en su propia aplicación; no lo dé por supuesto.

Otros costes de compilación que conviene revisar:

  • Telemetría. Defina NEXT_TELEMETRY_DISABLED=1 en CI para que la compilación no haga llamadas adicionales.
  • Generación estática que llama a APIs. Si generateStaticParams consulta un backend lento, la compilación espera. Apunte CI a un fixture o mock rápido.
  • Optimización de imágenes. Muchas imágenes remotas únicas ralentizan la compilación. La caché ayuda en las ejecuciones repetidas.
  • Source maps. Los source maps de producción para el navegador añaden tiempo. Desactívelos en las compilaciones de CI que solo use para tests.

Tests end-to-end con Playwright

Playwright suele ser el job más largo en un repositorio de Next.js. Compile una vez, suba la salida .next con actions/upload-artifact y ejecute next start en cada shard en lugar de recompilar en cada uno. Use el flag --shard=1/4 de Playwright con una matriz. La receta completa, incluida la caché del navegador, está en Playwright tests lentos y sharding de tests en GitHub Actions. La calculadora de shards ayuda a elegir el número de shards.

Lo que aportan más núcleos de CPU

next build, tsc, Turbopack y los workers de Playwright usan varios núcleos. Un runner de 2 vCPU deja gran parte de esa capacidad sin usar. Nuestros benchmarks incluyen dos stacks de Next.js, ejecutados el 8 de octubre de 2026 como ejecuciones completas de CI con 10 shards de pruebas y una base de datos real. Turborepo + Next.js + tRPC + MySQL pasó de 3m29s en un runner alojado en GitHub a 1m53s en compiler.dev (1.9x). Next.js + Supabase con Playwright pasó de 4m03s a 2m48s (1.4x). Son pipelines completos, no solo el paso de compilación, así que tómelos como una indicación y no como una promesa para su repositorio.

Para probarlo, cambiar es una sola línea, runs-on: [self-hosted, Linux, compiler-ci], después de instalar la GitHub App. La máquina predeterminada tiene 8 vCPU y 16 GB a $0.008 por minuto, y los jobs vuelven a sus runners originales si algo falla. Los detalles están en la página de precios y en la comparativa. También hay una plantilla de Next.js y una plantilla general de Node.

Lista de verificación

  1. Añada actions/cache para .next/cache con una clave de lockfile más código fuente y una clave de restauración.
  2. Use la caché de setup-node para el gestor de paquetes.
  3. Ejecute lint, comprobación de tipos, tests unitarios y compilación como jobs paralelos.
  4. Compile una vez para Playwright y divida los tests en shards.
  5. Añada concurrency y timeout-minutes.
  6. Pruebe más núcleos para el job de compilación y compare el coste por ejecución.

Preguntas frecuentes

¿Por qué next build dice "No Cache Detected"?

.next/cache estaba vacía en el momento de la compilación. Conserve esa carpeta entre ejecuciones con actions/cache, como se muestra arriba, y el mensaje desaparecerá en la siguiente ejecución.

¿Debo cachear node_modules en GitHub Actions?

Normalmente no. Cachee la caché de descargas del gestor de paquetes mediante actions/setup-node y ejecute un npm ci limpio. Un node_modules restaurado puede ocultar problemas del lockfile.

¿Turbopack hace innecesaria la caché?

No. Turbopack hace más rápida la compilación, pero .next/cache sigue almacenando resultados y acelera las compilaciones repetidas. Mida ambas cosas en su aplicación.

¿Cómo acelero las compilaciones de Next.js en un monorepo?

Compile solo las aplicaciones afectadas y use una caché remota. Consulte CI para monorepos con Nx o Turborepo.

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

Pruébelo gratis