Zum Inhalt springen

Node.js GitHub Actions Workflow-Vorlage

Zuletzt aktualisiert am

Dies ist eine vollständige .github/workflows/ci.yml für ein Node.js-Projekt mit npm. Sie installiert Abhängigkeiten aus einem Cache, führt Lint, Build und Tests auf zwei Node-Versionen aus und bricht veraltete Pull-Request-Läufe ab. Kopieren Sie sie, passen Sie die Skripte an Ihre package.json an und committen Sie.

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:
  test:
    runs-on: ubuntu-latest
    timeout-minutes: 15
    strategy:
      fail-fast: false
      matrix:
        node: [20, 22]
    steps:
      - uses: actions/checkout@v4

      - uses: actions/setup-node@v4
        with:
          node-version: ${{ matrix.node }}
          cache: npm

      - run: npm ci
      - run: npm run lint --if-present
      - run: npm run build --if-present
      - run: npm test

Was die nicht offensichtlichen Teile bewirken

  • permissions: contents: read beschränkt das automatische GITHUB_TOKEN auf Lesezugriff auf das Repository. Fügen Sie pro Job nur dann weitere Berechtigungen hinzu, wenn sie wirklich benötigt werden.
  • concurrency gibt jedem Pull Request eine eigene Gruppe. Ein neuer Push bricht den älteren Lauf ab. Pushes auf main werden nicht abgebrochen, sodass jeder Commit auf main ein Ergebnis erhält.
  • timeout-minutes: 15 verhindert, dass ein hängender Test den Standardwert von sechs Stunden ausschöpft. Setzen Sie ihn auf etwa das Doppelte Ihrer üblichen Laufzeit.
  • fail-fast: false lässt beide Node-Versionen vollständig durchlaufen, sodass Sie jeden Fehler sehen und nicht nur den ersten.
  • cache: npm sorgt dafür, dass setup-node den Download-Ordner von npm cacht (nicht node_modules), geschlüsselt über package-lock.json. npm ci installiert danach aus lokalen Tarballs. Details unter npm in GitHub Actions cachen.
  • npm ci installiert exakt das, was im Lockfile steht, und schlägt fehl, wenn es nicht synchron ist. Verwenden Sie es in CI anstelle von npm install.
  • --if-present überspringt nicht definierte Skripte, damit die Vorlage auch bei kleinen Projekten funktioniert.

Varianten

pnpm oder Yarn

Passen Sie die Cache-Option und den Installationsbefehl an. Für pnpm fügen Sie pnpm/action-setup@v4 vor setup-node hinzu und setzen cache: pnpm. Siehe pnpm cachen und Yarn cachen.

Monorepo

Führen Sie Aufgaben über Ihr Build-Tool aus und übergeben Sie einen Remote-Cache, damit unveränderte Pakete übersprungen werden. Siehe CI für Nx- und Turborepo-Monorepos.

Einen Deploy-Job hinzufügen

  deploy:
    needs: test
    if: github.ref == 'refs/heads/main'
    runs-on: ubuntu-latest
    permissions:
      contents: read
      id-token: write
    steps:
      - uses: actions/checkout@v4
      - run: ./scripts/deploy.sh

Verwenden Sie für Cloud-Zugangsdaten OIDC statt gespeicherter Schlüssel; siehe den Eintrag OIDC im Glossar.

macOS oder Windows

Ergänzen Sie die Matrix um os: [ubuntu-latest, macos-latest] und runs-on: ${{ matrix.os }}. Nutzen Sie diese nur, wenn Sie auf diesen Plattformen ausliefern, da sie pro Minute mehr kosten.

Auf schnelleren Maschinen ausführen

Wenn Ihre Tests der langsame Teil sind, ändern Sie eine Zeile und belassen Sie alles andere:

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

compiler.dev führt den Job auf einer frischen Maschine mit 8 vCPU / 16 GB aus. Sollte dies einmal nicht möglich sein, weicht der Job auf Ihren ursprünglichen Runner aus. Siehe Preise und wie Sie GitHub Actions beschleunigen.

FAQ

Sollte ich node_modules cachen?

In der Regel nein. Das Cachen des npm-Download-Caches und das Ausführen von npm ci ist sicherer, weil node_modules plattformspezifische Binärdateien enthalten kann und npm ci den Ordner ohnehin löscht.

Welche Node-Versionen sollte ich testen?

Die aktiven LTS-Linien, die Sie unterstützen. Prüfen Sie den Release-Plan von Node.js und entfernen Sie Versionen, deren Support ausgelaufen ist.

Wie führe ich Tests parallel aus?

Nutzen Sie die Worker Ihres Test-Runners lokal und Test-Sharding über mehrere Maschinen. Jest und Vitest unterstützen beide --shard.

Warum wird mein Cache nicht wiederhergestellt?

Meist ist der Pfad zum Lockfile falsch oder der Gültigkeitsbereich des Branches stimmt nicht. Lesen Sie über Cache-Schlüssel.