Erstellen und Testen von Node.js-Code

Hinweis: GitHub-gehostete Runner werden auf GitHub Enterprise Server derzeit nicht unterstützt. Weitere Informationen zur geplanten zukünftigen Unterstützung findest Du in der GitHub public roadmap.

Einführung

Diese Anleitung zeigt Dir, wie du einen Workflow für fortlaufende Integration (CI) erstellen kannst, der Node.js-Code baut und testet. Wenn deine CI-Tests erfolgreich durchlaufen, kannst du deinen Code deployen (bereitstellen) oder ein Paket veröffentlichen.

Voraussetzungen

Wir empfehlen, dass du ein grundlegendes Verständnis von Node.js, YAML, Workflowkonfigurations-Optionen und die Erstellung einer Workflow-Datei hast. Weitere Informationen findest du unter:

Verwendung von selbstgehosteten Runnern auf GitHub Enterprise Server

Wenn du Setup-Aktionen (wie z.B.actions/setup-LANGUAGE) auf GitHub Enterprise Server mit selbstgehosteten Runnern verwendest, musst du möglicherweise den Tools-Cache auf Runnern einrichten, die keinen Internetzugang haben. Weitere Informationen finden Sie unter Einrichten des Toolcaches auf selbstgehosteten Runnern ohne Internetzugriff.

Verwenden einer Node.js-Workflowvorlage

Fügen Sie für einen schnellen Einstieg dem Verzeichnis .github/workflows Ihres Repositorys eine Workflowvorlage hinzu.

GitHub bietet eine Workflowvorlage für Node.js, die für die meisten Node.js-Projekte funktionieren sollte. In den nachfolgenden Abschnitten dieser Anleitung finden Sie Beispiele dafür, wie diese Workflowvorlage angepasst werden kann.

Navigieren Sie auf GitHub zur Hauptseite des Repositorys.
Klicke unter dem Namen deines Repositorys auf Aktionen.
Wenn du bereits über einen Workflow im Repository verfügst, klicke auf Neuer Workflow.
Auf der Seite „Workflow auswählen“ wird eine Auswahl empfohlener Workflowvorlagen angezeigt. Suchen Sie nach „Node.js“.
Filtern Sie die Auswahl von Workflows, indem Sie auf Continuous Integration klicken.

Klicken Sie im Workflow „Node.js“ auf Konfigurieren.

Wenn Sie die Workflowvorlage „Node.js“ nicht finden, kopieren Sie den folgenden Workflowcode in eine neue Datei namens node.js.yml im Verzeichnis .github/workflows Ihres Repositorys.

YAML

name: Node.js CI

on:
  push:
    branches: [ "main" ]
  pull_request:
    branches: [ "main" ]

jobs:
  build:
    runs-on: ubuntu-latest

    strategy:
      matrix:
        node-version: [18.x, 20.x]
        # See supported Node.js release schedule at https://nodejs.org/en/about/releases/

    steps:
    - uses: actions/checkout@v4
    - name: Use Node.js ${{ matrix.node-version }}
      uses: actions/setup-node@v4
      with:
        node-version: ${{ matrix.node-version }}
        cache: 'npm'
    - run: npm ci
    - run: npm run build --if-present
    - run: npm test

name: Node.js CI

on:
  push:
    branches: [ "main" ]
  pull_request:
    branches: [ "main" ]

jobs:
  build:
    runs-on: ubuntu-latest

    strategy:
      matrix:
        node-version: [18.x, 20.x]
        # See supported Node.js release schedule at https://nodejs.org/en/about/releases/

    steps:
    - uses: actions/checkout@v4
    - name: Use Node.js ${{ matrix.node-version }}
      uses: actions/setup-node@v4
      with:
        node-version: ${{ matrix.node-version }}
        cache: 'npm'
    - run: npm ci
    - run: npm run build --if-present
    - run: npm test

Bearbeiten Sie den Workflow nach Bedarf. Ändern Sie beispielsweise die Node-Versionen, die Sie verwenden möchten.
Klicke auf Änderungen committen.

Die Node.js-Version angeben

Der einfachste Weg, eine Node.js-Version anzugeben, bietet die Aktion setup-node von GitHub. Weitere Informationen findest du unter setup-node.

Von der Aktion setup-node wird eine Node.js-Version als Eingabe verwendet und auf dem Runner konfiguriert. Mit dieser Aktion setup-node wird im Toolcache der jeweiligen Runner nach einer bestimmten Version von Node.js gesucht, und die erforderlichen Binärdateien werden in PATH hinzugefügt, der für den Rest des Auftrags bestehen bleibt. Die Aktion setup-node wird als Methode zur Verwendung von Node.js mit GitHub Actions empfohlen, da damit ein konsistentes Verhalten bei verschiedenen Runnern und verschiedenen Version von Node.js gewährleistet wird. Wenn du einen selbst gehosteten Runner verwendest, musst du Node.js installieren und in PATH hinzufügen.

Die Workflowvorlage umfasst eine Matrixstrategie, die den Code mit den in node-version aufgeführten Node.js-Versionen erstellt und testet. Das „x“ in der Versionsnummer ist ein Platzhalterzeichen für das neueste Neben- und Patchrelease einer Version. Von jeder im node-version-Array angegebenen Version von Node.js wird ein Auftrag erstellt, bei dem dieselben Schritte ausgeführt werden.

Jeder Auftrag kann mithilfe des matrix-Kontexts auf den im Matrixarray node-version definierten Wert zugreifen. Die Aktion setup-node verwendet den Kontext als node-version-Eingabe. Die Aktion setup-node konfiguriert jeden Auftrag mit einer anderen Node.js-Version, bevor sie den Code erstellt und testet. Weitere Informationen zu Matrixstrategien und -kontexten findest du unter Workflowsyntax für GitHub Actions und Zugreifen auf kontextbezogene Informationen zu Workflowausführungen.

YAML

strategy:
  matrix:
    node-version: ['18.x', '20.x']

steps:
- uses: actions/checkout@v4
- name: Use Node.js ${{ matrix.node-version }}
  uses: actions/setup-node@v4
  with:
    node-version: ${{ matrix.node-version }}

strategy:
  matrix:
    node-version: ['18.x', '20.x']

steps:
- uses: actions/checkout@v4
- name: Use Node.js ${{ matrix.node-version }}
  uses: actions/setup-node@v4
  with:
    node-version: ${{ matrix.node-version }}

Alternativ kannnst du auch mit genauen Node.js-Versionen bauen und testen.

YAML

strategy:
  matrix:
    node-version: ['10.17.0', '17.9.0']

strategy:
  matrix:
    node-version: ['10.17.0', '17.9.0']

Oder du kannst auch mithilfe einer einzelnen Version von Node.js bauen und testen.

YAML

name: Node.js CI

on: [push]

jobs:
  build:

    runs-on: ubuntu-latest

    steps:
      - uses: actions/checkout@v4
      - name: Use Node.js
        uses: actions/setup-node@v4
        with:
          node-version: '20.x'
      - run: npm ci
      - run: npm run build --if-present
      - run: npm test

name: Node.js CI

on: [push]

jobs:
  build:

    runs-on: ubuntu-latest

    steps:
      - uses: actions/checkout@v4
      - name: Use Node.js
        uses: actions/setup-node@v4
        with:
          node-version: '20.x'
      - run: npm ci
      - run: npm run build --if-present
      - run: npm test

Wenn du keine Node.js Version festlegst, verwendet GitHub die standardmäßige Node.js Version der Umgebung. Weitere Informationen findest du unter Verwenden von auf GitHub gehosteten Runnern.

Installieren von Abhängigkeiten

Auf GitHub-gehosteten Runnern sind die Abhängigkeitsmanager npm und Yarn installiert. Du kannst npm und Yarn verwenden, um in deinem Workflow Abhängigkeiten zu installieren, bevor du deinen Code kompilierst und testest. Die auf GitHub gehosteten Windows- und Linux-Runner haben auch Grunt, Gulp und Bower installiert.

Sie können auch Abhängigkeiten zwischenspeichern, um Ihren Workflow zu beschleunigen. Weitere Informationen findest du unter Abhängigkeiten zwischenspeichern um Workflows zu beschleunigen.

Beispiel mit npm

In diesem Beispiel werden die Versionen aus der Datei package-lock.json oder npm-shrinkwrap.json installiert und verhindert, dass Updates an der Sperrdatei vorgenommen werden. Die Verwendung von npm ci ist im Allgemeinen schneller als die Ausführung von npm install. Weitere Informationen findest du unter npm ci und Einführung in npm ci für schnellere, zuverlässigere Builds.

YAML

steps:
- uses: actions/checkout@v4
- name: Use Node.js
  uses: actions/setup-node@v4
  with:
    node-version: '20.x'
- name: Install dependencies
  run: npm ci

steps:
- uses: actions/checkout@v4
- name: Use Node.js
  uses: actions/setup-node@v4
  with:
    node-version: '20.x'
- name: Install dependencies
  run: npm ci

Mit npm install werden die in der Datei package.json definierten Abhängigkeiten installiert. Weitere Informationen findest du unter npm install.

YAML

steps:
- uses: actions/checkout@v4
- name: Use Node.js
  uses: actions/setup-node@v4
  with:
    node-version: '20.x'
- name: Install dependencies
  run: npm install

steps:
- uses: actions/checkout@v4
- name: Use Node.js
  uses: actions/setup-node@v4
  with:
    node-version: '20.x'
- name: Install dependencies
  run: npm install

Beispiel mit Yarn

In diesem Beispiel werden die in der Datei yarn.lock definierten Abhängigkeiten installiert, und Updates der Datei yarn.lock werden verhindert. Weitere Informationen findest du unter yarn install.

YAML

steps:
- uses: actions/checkout@v4
- name: Use Node.js
  uses: actions/setup-node@v4
  with:
    node-version: '20.x'
- name: Install dependencies
  run: yarn --frozen-lockfile

steps:
- uses: actions/checkout@v4
- name: Use Node.js
  uses: actions/setup-node@v4
  with:
    node-version: '20.x'
- name: Install dependencies
  run: yarn --frozen-lockfile

Alternativ kannst du die in der Datei package.json definierten Abhängigkeiten installieren.

YAML

steps:
- uses: actions/checkout@v4
- name: Use Node.js
  uses: actions/setup-node@v4
  with:
    node-version: '20.x'
- name: Install dependencies
  run: yarn

steps:
- uses: actions/checkout@v4
- name: Use Node.js
  uses: actions/setup-node@v4
  with:
    node-version: '20.x'
- name: Install dependencies
  run: yarn

Beispiel mit einer privaten Registry und Erstellung der Datei .npmrc

Du kannst die setup-node-Aktion verwenden, um auf dem Runner eine lokale NPMRC-Datei zu erstellen, in der die Standardregistrierung und der Standardbereich konfiguriert werden. Die setup-node-Aktion akzeptiert als Eingabe auch ein Authentifizierungstoken, das für den Zugriff auf private Registrierungen oder die Veröffentlichung von Knotenpaketen verwendet wird. Weitere Informationen findest du unter setup-node.

Um dich bei deiner privaten Registry zu authentifizieren, musst du dein npm-Authentifizierungstoken als Geheimnis speichern. Erstelle beispielsweise ein Repositorygeheimnis namens NPM_TOKEN. Weitere Informationen findest du unter Verwenden von Geheimnissen in GitHub-Aktionen.

Im folgenden Beispiel enthält das Geheimnis NPM_TOKEN das npm-Authentifizierungstoken. Die Aktion setup-node konfiguriert die NPMRC-Datei, um das npm-Authentifizierungstoken aus der Umgebungsvariable NODE_AUTH_TOKEN zu lesen. Wenn du die Aktion setup-node zum Erstellen einer NPMRC-Datei verwendest, musst du die Umgebungsvariable NODE_AUTH_TOKEN mit dem Geheimen festlegen, der dein npm-Authentifizierungstoken enthält.

Verwende vor der Installation von Abhängigkeiten die Aktion setup-node, um die NPMRC-Datei zu erstellen. Die Aktion hat zwei Eingabeparameter. Der Parameter node-version legt die Node.js-Version fest, und der Parameter registry-url legt die Standardregistrierung fest. Wenn deine Paketregistrierung Geltungsbereiche verwendet, musst du den Parameter scope verwenden. Weitere Informationen findest du unter npm-scope.

YAML

steps:
- uses: actions/checkout@v4
- name: Use Node.js
  uses: actions/setup-node@v4
  with:
    always-auth: true
    node-version: '20.x'
    registry-url: https://registry.npmjs.org
    scope: '@octocat'
- name: Install dependencies
  run: npm ci
  env:
    NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}

steps:
- uses: actions/checkout@v4
- name: Use Node.js
  uses: actions/setup-node@v4
  with:
    always-auth: true
    node-version: '20.x'
    registry-url: https://registry.npmjs.org
    scope: '@octocat'
- name: Install dependencies
  run: npm ci
  env:
    NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}

Das obige Beispiel erstellt eine NPMRC-Datei mit folgendem Inhalt:

//registry.npmjs.org/:_authToken=${NODE_AUTH_TOKEN}
@octocat:registry=https://registry.npmjs.org/
always-auth=true

Beispiel zum Zwischenspeichern von Abhängigkeiten im Cache

Du kannst die Abhängigkeiten mithilfe der Aktion setup-node zwischenspeichern und wiederherstellen.

Im folgenden Beispiel werden Abhängigkeiten für npm zwischengespeichert.

YAML

steps:
- uses: actions/checkout@v4
- uses: actions/setup-node@v4
  with:
    node-version: '20'
    cache: 'npm'
- run: npm install
- run: npm test

steps:
- uses: actions/checkout@v4
- uses: actions/setup-node@v4
  with:
    node-version: '20'
    cache: 'npm'
- run: npm install
- run: npm test

Im folgenden Beispiel werden Abhängigkeiten für Yarn zwischengespeichert.

YAML

steps:
- uses: actions/checkout@v4
- uses: actions/setup-node@v4
  with:
    node-version: '20'
    cache: 'yarn'
- run: yarn
- run: yarn test

steps:
- uses: actions/checkout@v4
- uses: actions/setup-node@v4
  with:
    node-version: '20'
    cache: 'yarn'
- run: yarn
- run: yarn test

Im folgenden Beispiel werden Abhängigkeiten für pnpm (ab Version 6.10) zwischengespeichert.

YAML

# Dieser Workflow verwendet Aktionen, die nicht von GitHub zertifiziert sind.
# Sie werden von einem Drittanbieter bereitgestellt und unterliegen
# separaten Nutzungsbedingungen, Datenschutzbestimmungen und Support
# Onlinedokumentation.

# NOTE: pnpm caching support requires pnpm version >= 6.10.0

steps:
- uses: actions/checkout@v4
- uses: pnpm/action-setup@0609f0983b7a228f052f81ef4c3d6510cae254ad
  with:
    version: 6.10.0
- uses: actions/setup-node@v4
  with:
    node-version: '20'
    cache: 'pnpm'
- run: pnpm install
- run: pnpm test

# Dieser Workflow verwendet Aktionen, die nicht von GitHub zertifiziert sind.
# Sie werden von einem Drittanbieter bereitgestellt und unterliegen
# separaten Nutzungsbedingungen, Datenschutzbestimmungen und Support
# Onlinedokumentation.

# NOTE: pnpm caching support requires pnpm version >= 6.10.0

steps:
- uses: actions/checkout@v4
- uses: pnpm/action-setup@0609f0983b7a228f052f81ef4c3d6510cae254ad
  with:
    version: 6.10.0
- uses: actions/setup-node@v4
  with:
    node-version: '20'
    cache: 'pnpm'
- run: pnpm install
- run: pnpm test

Wenn du eine benutzerdefinierte Anforderung verwenden oder genauere Steuerungsmöglichkeiten zum Zwischenspeichern benötigst, kannst du die Aktion cache verwenden. Weitere Informationen findest du unter Abhängigkeiten zwischenspeichern um Workflows zu beschleunigen.

Deinen Code bauen und testen

Du kannst die gleichen Befehle verwenden, die du auch lokal verwendest, um deinen Code zu bauen und zu testen. Wenn du beispielsweise npm run build ausführst, um die in der Datei package.json definierten Buildschritte auszuführen, und npm test, um deine Testsuite auszuführen, fügst du diese Befehle in der Workflowdatei hinzu.

YAML

steps:
- uses: actions/checkout@v4
- name: Use Node.js
  uses: actions/setup-node@v4
  with:
    node-version: '20.x'
- run: npm install
- run: npm run build --if-present
- run: npm test

steps:
- uses: actions/checkout@v4
- name: Use Node.js
  uses: actions/setup-node@v4
  with:
    node-version: '20.x'
- run: npm install
- run: npm run build --if-present
- run: npm test

Workflow-Daten als Artefakte paketieren

Du kannst Artefakte aus deinen Build- und Testschritten speichern, um sie nach dem Abschluss eines Jobs anzuzeigen. Zum Beispiel kann es notwendig sein, Logdateien, Core Dumps, Testergebnisse oder Screenshots zu speichern. Weitere Informationen findest du unter Speichern und Freigeben von Daten aus einem Workflow.

In Paket-Registries veröffentlichen

Du kannst deinen Workflow so konfigurieren, dass dein Node.js-Paket nach Bestehen deiner CI-Tests in einer Paket-Registry veröffentlicht wird. Weitere Informationen zum Veröffentlichen in npm und GitHub Packages findest du unter Node.js-Pakete veröffentlichen.

Erstellen und Testen von Node.js-Code

In diesem Artikel