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: npmalmacena 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/cachees 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 querestore-keysrecurre a la más reciente anterior para un build incremental. npx tsc --noEmitcomprueba los tipos sin escribir archivos.next buildtambién comprueba los tipos, pero ejecutarlo primero ofrece un fallo más rápido y más claro.NEXT_TELEMETRY_DISABLEDdesactiva la telemetría anónima en CI.concurrencycancela las ejecuciones anteriores en la misma pull request. La rama main nunca se cancela.timeout-minuteslimita 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.
Relacionado
- Acelere Next.js en GitHub ActionsAcelere las compilaciones de Next.js en GitHub Actions con caché de .next/cache y del gestor de paquetes, jobs de lint y test separados y sharding de Playwright.
- Plantilla de flujo de trabajo de GitHub Actions para .NETCI de GitHub Actions para .NET listo para copiar: caché de NuGet, restauración, compilación, pruebas, servicio SQL Server, concurrencia y permisos.
- Plantilla de flujo de trabajo de GitHub Actions para DjangoCI de GitHub Actions para Django, listo para copiar y pegar: contenedor de servicio Postgres, caché de pip, comprobación de migraciones y tests.
- Plantilla de workflow de GitHub Actions para compilar DockerFlujo de trabajo de GitHub Actions para copiar y pegar: compile imágenes Docker con Buildx, capas en caché de GitHub y publique en GHCR desde main.