Next.js GitHub Actions Workflow-Vorlage
Zuletzt aktualisiert am
Dies ist eine funktionierende .github/workflows/ci.yml für eine Next.js-App mit npm. Sie cacht npm-Downloads und den .next/cache-Build-Cache und führt anschließend Lint, eine Typprüfung, Tests und einen Production-Build aus. Passen Sie die Skriptnamen an Ihre package.json an.
Der Workflow
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
Was die nicht offensichtlichen Teile bewirken
cache: npmcacht den npm-Download-Ordner, gesteuert über die Lockfile. Siehe npm cachen.- Der Schritt
.next/cachewird in den meisten Vorlagen übersehen. Next.js speichert dort kompilierte Ausgaben und Ergebnisse der Bildoptimierung. Ohne wiederhergestellten Cache startet jeder Build von vorn, und Next.js gibt eine entsprechende Warnung aus. Der Schlüssel kombiniert den Hash der Lockfile mit einem Hash der Quelldateien, sodass eine Codeänderung einen neuen Eintrag erzeugt, währendrestore-keysfür einen inkrementellen Build auf den jüngsten älteren Eintrag zurückgreift. npx tsc --noEmitführt die Typprüfung aus, ohne Dateien zu schreiben.next buildprüft ebenfalls die Typen, aber wenn Sie dies vorab ausführen, schlägt der Job schneller und mit klarerer Fehlermeldung fehl.NEXT_TELEMETRY_DISABLEDdeaktiviert die anonyme Telemetrie in der CI.concurrencybricht ältere Läufe auf demselben Pull Request ab. Der Main-Branch wird nie abgebrochen.timeout-minutesbegrenzt einen hängenden Build.
Varianten
Umgebungsvariablen zur Build-Zeit
Variablen mit dem Präfix NEXT_PUBLIC_ werden beim Build eingebettet. Übergeben Sie sie mit env: im Build-Schritt und halten Sie echte Secrets aus dem Client-Bundle heraus.
End-to-End-Tests mit Playwright
Fügen Sie npx playwright install --with-deps chromium und npx playwright test hinzu. Teilen Sie die Tests mit einer Matrix auf; siehe Test-Sharding und langsame Playwright-Tests.
Monorepo mit Turborepo
Führen Sie npx turbo run lint test build mit gesetzten TURBO_TOKEN und TURBO_TEAM aus, um einen Remote-Build-Cache zu nutzen. Mehr dazu unter Nx- und Turborepo-CI.
Deploy-Job
Fügen Sie einen zweiten Job mit needs: ci und if: github.ref == 'refs/heads/main' hinzu. Vercel-Nutzer können dies überspringen und die Git-Integration von Vercel deployen lassen.
macOS
Für eine Web-App selten sinnvoll. Bleiben Sie bei Linux.
Auf schnelleren Maschinen ausführen
Next.js-Builds sind rechenintensiv, da SWC und die Typprüfung mehrere Kerne nutzen. Ändern Sie eine Zeile:
runs-on: [self-hosted, Linux, compiler-ci]
Damit läuft der Job auf einer Maschine mit 8 vCPUs von compiler.dev, mit Fallback auf Ihren bisherigen Runner. Die vollständige Liste der Optimierungen finden Sie unter Next.js auf GitHub Actions beschleunigen.
FAQ
Warum warnt mein Next.js-Build vor fehlendem Cache?
Der Ordner .next/cache war leer. Fügen Sie den oben genannten Cache-Schritt hinzu, dann verschwindet die Warnung beim nächsten Lauf, der den Cache wiederherstellt.
Sollte ich node_modules für Next.js cachen?
Nein. Cachen Sie die npm-Downloads und lassen Sie npm ci node_modules neu aufbauen.
Kann ich pnpm oder Yarn verwenden?
Ja. Ändern Sie cache: und den Installationsbefehl und passen Sie den Namen der Lockfile im Schlüssel an. Siehe pnpm-Caching.
Brauche ich Docker für die CI?
Nein. Bauen Sie im Job selbst. Verwenden Sie Docker nur, wenn Sie einen Container deployen; siehe Docker-Layer-Caching.
Verwandt
- Next.js in GitHub Actions beschleunigenNext.js-Builds in GitHub Actions beschleunigen: .next/cache, Paket-Manager-Cache, getrennte Lint- und Test-Jobs und Playwright-Sharding. Funktionierendes YAML.
- .NET GitHub Actions Workflow-VorlageFertige GitHub-Actions-CI für .NET mit NuGet-Cache, Restore-, Build- und Test-Schritten, optionalem SQL-Server-Dienst, Concurrency und Berechtigungen.
- Django GitHub Actions Workflow-VorlageFertige GitHub-Actions-CI für Django mit Postgres-Service-Container, pip-Caching, Migrationsprüfung und Tests sowie Concurrency und Berechtigungen.
- Docker Build GitHub Actions Workflow VorlageFertiger GitHub-Actions-Workflow zum Bauen von Docker-Images mit Buildx, GitHub-Cache-Layern und einem Push zu GHCR auf main, mit minimalen Berechtigungen.