Zum Inhalt springen

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: npm cacht den npm-Download-Ordner, gesteuert über die Lockfile. Siehe npm cachen.
  • Der Schritt .next/cache wird 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ährend restore-keys für einen inkrementellen Build auf den jüngsten älteren Eintrag zurückgreift.
  • npx tsc --noEmit führt die Typprüfung aus, ohne Dateien zu schreiben. next build prüft ebenfalls die Typen, aber wenn Sie dies vorab ausführen, schlägt der Job schneller und mit klarerer Fehlermeldung fehl.
  • NEXT_TELEMETRY_DISABLED deaktiviert die anonyme Telemetrie in der CI.
  • concurrency bricht ältere Läufe auf demselben Pull Request ab. Der Main-Branch wird nie abgebrochen.
  • timeout-minutes begrenzt 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.