Saltar al contenido

Plantilla de flujo de trabajo de GitHub Actions para Next.js

Última actualización

Este es un .github/workflows/ci.yml funcional para una aplicación Next.js con npm. Almacena en caché las descargas de npm y la caché de compilación .next/cache, y después ejecuta lint, una comprobación de tipos, las pruebas y un build de producción. Modifique los nombres de los scripts para que coincidan con su package.json.

El flujo de trabajo

name: CI

on:
  push:
    branches: [main]
  pull_request:

permissions:
  contents: read

concurrency:
  group: ci-${{ github.workflow }}-${{ github.event.pull_request.number || github.ref }}
  cancel-in-progress: ${{ github.event_name == 'pull_request' }}

jobs:
  ci:
    runs-on: ubuntu-latest
    timeout-minutes: 20
    env:
      NEXT_TELEMETRY_DISABLED: "1"
    steps:
      - uses: actions/checkout@v4

      - uses: actions/setup-node@v4
        with:
          node-version: 22
          cache: npm

      - name: Cache Next.js build cache
        uses: actions/cache@v4
        with:
          path: .next/cache
          key: nextjs-${{ runner.os }}-${{ hashFiles('package-lock.json') }}-${{ hashFiles('**/*.js', '**/*.jsx', '**/*.ts', '**/*.tsx', '!node_modules/**', '!.next/**') }}
          restore-keys: |
            nextjs-${{ runner.os }}-${{ hashFiles('package-lock.json') }}-
            nextjs-${{ runner.os }}-

      - run: npm ci
      - run: npm run lint
      - run: npx tsc --noEmit
      - run: npm test --if-present
      - run: npm run build

Qué hacen las partes menos evidentes

  • cache: npm almacena en caché la carpeta de descargas de npm, con la clave basada en el lockfile. Consulte cómo almacenar en caché npm.
  • El paso de .next/cache es el que más plantillas omiten. Next.js guarda ahí la salida compilada y los resultados de la optimización de imágenes. Sin una caché restaurada, cada build comienza desde cero y Next.js muestra una advertencia al respecto. La clave combina el hash del lockfile con un hash de los archivos fuente, de modo que un cambio de código genera una entrada nueva, mientras que restore-keys recurre a la más reciente anterior para un build incremental.
  • npx tsc --noEmit comprueba los tipos sin escribir archivos. next build también comprueba los tipos, pero ejecutarlo primero ofrece un fallo más rápido y más claro.
  • NEXT_TELEMETRY_DISABLED desactiva la telemetría anónima en CI.
  • concurrency cancela las ejecuciones anteriores en la misma pull request. La rama main nunca se cancela.
  • timeout-minutes limita un build bloqueado.

Variantes

Variables de entorno en el momento del build

Las variables con el prefijo NEXT_PUBLIC_ se incrustan durante el build. Páselas con env: en el paso de build y mantenga los secretos reales fuera del bundle del cliente.

Tests end-to-end con Playwright

Añada npx playwright install --with-deps chromium y npx playwright test. Divídalo en fragmentos con una matrix; consulte fragmentación de pruebas y pruebas lentas de Playwright.

Monorepo con Turborepo

Ejecute npx turbo run lint test build con TURBO_TOKEN y TURBO_TEAM definidos para usar una caché de build remota. Más información en CI de Nx y Turborepo.

Job de despliegue

Añada un segundo job con needs: ci y if: github.ref == 'refs/heads/main'. Los usuarios de Vercel pueden omitirlo y dejar que la integración Git de Vercel realice el despliegue.

macOS

Rara vez es útil para una aplicación web. Manténgase en Linux.

Ejecútelo en máquinas más rápidas

Los builds de Next.js consumen mucha CPU, porque SWC y la comprobación de tipos usan varios núcleos. Cambie una línea:

    runs-on: [self-hosted, Linux, compiler-ci]

Eso traslada el job a una máquina de 8 vCPU de compiler.dev, con una alternativa a su runner actual. La lista completa de ajustes está en cómo acelerar Next.js en GitHub Actions.

Preguntas frecuentes

¿Por qué mi build de Next.js advierte que no hay caché?

La carpeta .next/cache estaba vacía. Añada el paso de caché anterior y la advertencia desaparecerá en la siguiente ejecución que la restaure.

¿Debo almacenar node_modules en caché para Next.js?

No. Almacene en caché las descargas de npm y deje que npm ci reconstruya node_modules.

¿Puedo usar pnpm o Yarn?

Sí. Cambie cache: y el comando de instalación, y actualice el nombre del lockfile en la clave. Consulte caché de pnpm.

¿Necesito Docker para CI?

No. Realice el build en el job. Use Docker solo si despliega un contenedor; consulte caché de capas de Docker.