Webpack-Version Prüfen: Terminal, package.json und Config

Die fünf Major-Versionen von Webpack sind keine Drop-in-Ersätze füreinander. Jedes Major-Release führte Breaking Changes in der Konfigurationssyntax, der Loader-Kompatibilität und den Plugin-APIs ein. Eine Webpack-4-Config funktioniert nicht ohne Modifikationen mit Webpack 5, und für Webpack 3 veröffentlichte Loader können in Webpack 4+ still scheitern oder falsche Ausgaben erzeugen.

Über die Konfigurationskompatibilität hinaus beeinflusst die Webpack-Version die Performance. Webpack 5 führte persistentes Caching, Module Federation und verbessertes Tree-Shaking ein, das Build-Zeiten und Bundle-Größen im Vergleich zu Webpack 4 deutlich reduzieren kann. Wenn Sie einen langsamen Build debuggen oder eine Bundle-Größen-Regression untersuchen, ist das Bestätigen der Version der erste Diagnoseschritt.

Wenn Versionskonflikte Fehler verursachen

• Loader-Inkompatibilität - `babel-loader` v8 zielt auf Webpack 4 ab; die Verwendung mit Webpack 5 ohne Aktualisierung führt zu stiller Fehlkonfiguration.
• Plugin-API-Abweichungen - Plugins, die sich in den Webpack-Compiler einklinken, verwenden eine API, die sich zwischen v4 und v5 geändert hat. Ein für v4 gebautes Plugin wirft einen Fehler auf einem v5-Compiler-Objekt.
• Peer-Dependency-Konflikte - Tools wie `webpack-dev-server`, `html-webpack-plugin` und `mini-css-extract-plugin` veröffentlichen Versionen, die an bestimmte Webpack-Major-Versionen gebunden sind.
• CSS-Loader-Schemafehler - css-loader v5 und v6 haben strenge Schema-Validierung; ein Versionskonflikt mit Webpack erzeugt den Fehler „ValidationError: Invalid options object".

Das Terminal ist der schnellste und zuverlässigste Weg, Ihre Webpack-Version zu prüfen. Es gibt drei Befehle, die man kennen sollte, jeder für eine etwas andere Situation geeignet.

Webpack wird lokal in Ihrem Projekt als devDependency installiert. Die global installierte Version, falls vorhanden, ist fast nie die, die Ihr Build tatsächlich verwendet.

Die projektlokale Version (am zuverlässigsten)

Ihr Projekt installiert Webpack mit ziemlicher Sicherheit als lokale devDependency, nicht als globales Paket. Um die Version zu prüfen, die Ihre Build-Skripte tatsächlich verwenden, führen Sie `npx` oder `./node_modules/.bin/webpack` direkt aus dem Projektstamm aus. Diese Befehle umgehen jede globale Webpack-Installation und melden die lokal installierte Version.

# Am zuverlässigsten - nutzt die lokale node_modules-Installation
npx webpack --version

# Alternativer pfadbasierter Aufruf
./node_modules/.bin/webpack --version

# Mit yarn
yarn webpack --version

# Pnpm
pnpm exec webpack --version

Der npm-list-Befehl

`npm list webpack` fragt Ihre lokalen `node_modules` ab und gibt die installierte Version zusammen mit ihrer Position im Abhängigkeitsbaum aus. Dies ist nützlich, wenn Sie nicht nur die Version sehen wollen, sondern auch, welches Paket Webpack als Peer-Dependency angefordert hat — eine häufige Quelle von Versionskonflikten, wenn ein Build-Tool von einem bestimmten Webpack-Bereich abhängt.

# Webpack-Version in lokalem node_modules anzeigen
npm list webpack

# Alle Pakete im Baum anzeigen, die von Webpack abhängen
npm list webpack --all

# Yarn-Äquivalent
yarn list --pattern webpack

# Pnpm-Äquivalent
pnpm list webpack

Die global installierte Version

Wenn Sie Webpack global mit `npm install -g webpack webpack-cli` installiert haben, können Sie diese Version separat prüfen. Beachten Sie, dass die globale Version selten die ist, die die Builds Ihres Projekts verwenden — die meisten Build-Skripte rufen Webpack über `package.json`-Skripte auf, die immer zur lokalen Installation auflösen.

# Prüfung der globalen Installation
webpack --version

# Oder explizit aus dem globalen Pfad
npm list -g webpack

Die Datei `package.json` Ihres Projekts listet den Webpack-Versionsbereich auf, den Ihr Projekt als Abhängigkeit deklariert hat. Das ist nicht dasselbe wie die installierte Version — es ist der Bereich, der beim Hinzufügen von Webpack angegeben wurde, und die tatsächlich installierte Version kann jede Version innerhalb dieses Bereichs sein.

{
  "devDependencies": {
    "webpack": "^5.88.0",
    "webpack-cli": "^5.1.4",
    "webpack-dev-server": "^4.15.1"
  }
}

# In package-lock.json (npm)
grep '"webpack"' package-lock.json | head -5

# In yarn.lock
grep 'webpack@' yarn.lock | head -5

# In pnpm-lock.yaml
grep 'webpack' pnpm-lock.yaml | head -10

Manchmal müssen Sie die Webpack-Version zur Build-Zeit kennen — zum Beispiel, um je nach Major-Version einen anderen Konfigurationszweig anzuwenden oder Diagnoseinformationen in einer CI-Pipeline zu protokollieren. Webpack legt seine Version als Eigenschaft auf dem Compiler-Objekt offen, und das Webpack-Paket selbst exportiert einen `version`-String.

Version in webpack.config.js lesen

const webpack = require('webpack');

// Der Versions-String ist direkt verfügbar
console.log('Webpack version:', webpack.version);

// Verwendung für bedingte Konfiguration
const isWebpack5 = parseInt(webpack.version, 10) >= 5;

module.exports = {
  // ...
  plugins: [
    isWebpack5
      ? new webpack.ids.DeterministicModuleIdsPlugin()
      : new webpack.HashedModuleIdsPlugin(),
  ],
};

Version in einem eigenen Plugin oder Loader lesen

Innerhalb eines Webpack-Plugins trägt das Compiler-Objekt die Webpack-Version über `compiler.webpack.version`. Dies ist die sicherste programmatische Prüfung, weil sie die Version der Webpack-Instanz liest, die das Plugin aufgerufen hat — nicht die, die zufällig in `node_modules` installiert ist.

class MyPlugin {
  apply(compiler) {
    // compiler.webpack ist in Webpack 5+ verfügbar
    const version = compiler.webpack?.version ?? webpack.version;
    console.log('Running on webpack', version);

    compiler.hooks.done.tap('MyPlugin', (stats) => {
      // Build complete
    });
  }
}

Version in einer CI-Umgebung prüfen

In einer CI-Pipeline ist der sauberste Weg, die Webpack-Version zu protokollieren, ein Schritt, der `npx webpack --version` ausführt und die Ausgabe erfasst. Damit erhalten Sie die lokal installierte Version aus den exakten `node_modules`, die der Build verwenden wird, und sie erscheint bei jedem Lauf im Pipeline-Protokoll — nützlich beim Debuggen von Build-Fehlern, die nur auf bestimmten Runnern auftreten.

steps:
  - uses: actions/checkout@v4
  - uses: actions/setup-node@v4
    with:
      node-version: '20'
  - run: npm ci
  - name: Log webpack version
    run: npx webpack --version
  - name: Build
    run: npm run build

Die Unterschiede zwischen den Webpack-Major-Versionen zu verstehen, hilft Ihnen zu entscheiden, ob Ihre aktuelle Version für Ihr Projekt geeignet ist und was bei einer Migration zu erwarten ist. Hier ein kompakter Vergleich der Fähigkeiten und der Kompatibilitätslandschaft über alle fünf Major-Releases.

Webpack 4 vs. Webpack 5 - wesentliche Unterschiede

• Persistenter Cache - Webpack 5 cacht Kompilationsergebnisse zwischen Läufen auf der Festplatte; ein warmer Cache kann Rebuilds 5-10× schneller machen als Webpack 4.
• Module Federation - Webpack 5 führte Module Federation ein, um Code zwischen unabhängig deployten Frontends zur Laufzeit zu teilen.
• Asset-Module - Webpack 5 ersetzt `file-loader`, `url-loader` und `raw-loader` durch eingebaute Asset-Modul-Typen (`asset/resource`, `asset/inline` usw.).
• Node.js-Polyfills entfernt - Webpack 5 polyfillt Node.js-Kernmodule nicht mehr automatisch. Projekte, die von Polyfills für `buffer`, `path`, `stream` usw. abhingen, müssen sie explizit hinzufügen.
• Langfristiges Caching - Webpack 5 verwendet standardmäßig deterministische Chunk-IDs, was stabile Dateinamen über Builds hinweg erzeugt und Browser-Cache-Trefferquoten verbessert.

Versionskonflikte zwischen Webpack und seinem Ökosystem sind die häufigste Quelle verwirrender Build-Fehler. Die meisten dieser Fehler lassen sich auf eine von drei Ursachen zurückführen: mehrere Webpack-Kopien in `node_modules`, ein für eine andere Major-Version gebauter Loader oder Plugin oder ein abweichender Peer-Dependency-Bereich.

Mehrere Webpack-Kopien in node_modules

Es ist möglich — und überraschend häufig —, mehr als eine Kopie von Webpack in Ihrem Projekt installiert zu haben. Das passiert, wenn eine Abhängigkeit eine Peer-Dependency auf Webpack mit einem anderen Major-Versionsbereich deklariert als Ihr Projekt verwendet. Das Ergebnis sind zwei inkompatible Webpack-Instanzen, wodurch Plugins still scheitern oder abstürzen, weil sie gegen die eine Instanz registriert, aber von der anderen aufgerufen werden.

# Mehrere Webpack-Einträge im vollen Abhängigkeitsbaum prüfen
npm list webpack --all

# Nach mehr als einer eindeutigen Versionsnummer in der Ausgabe suchen
# z. B. wenn sowohl [email protected] als auch [email protected] erscheinen,
# ist das ein Zeichen für widersprüchliche Peer-Dependencies

Peer-Dependency-Konflikte auflösen

Wenn `npm list webpack --all` mehrere Webpack-Versionen zeigt, schauen Sie, welches Paket die ältere Version hereinzieht. Aktualisieren Sie dieses Paket auf eine Version, die Ihre Webpack-Major-Version unterstützt, oder verwenden Sie das Feld `resolutions` (Yarn) bzw. `overrides` (npm 8+), um alle Pakete auf eine einzige Webpack-Version zu zwingen.

{
  "overrides": {
    "webpack": "^5.88.0"
  }
}

{
  "resolutions": {
    "webpack": "^5.88.0"
  }
}

Semver-Bereiche validieren

Peer-Dependency-Bereiche wie `"webpack": "^4 || ^5"` und `"webpack": ">=4.41.0 <6"` sind gültige Semver-Ausdrücke, aber leicht falsch zu lesen. Der Semver-Validator von Aback Tools prüft jede Versionszeichenkette oder einen Bereichsausdruck gegen die Semver-2.0.0-Spezifikation — nützlich, wenn Sie eine Bibliothek schreiben, die einen Webpack-Peer-Dependency-Bereich deklariert, und bestätigen wollen, dass der Ausdruck korrekt geformt ist.

Ihre aktuelle Webpack-Version zu kennen ist erst der Anfang. Sie gut zu verwalten — sodass die Version über Umgebungen hinweg konsistent bleibt, für jeden Beitragenden sichtbar ist und absichtlich statt versehentlich aktualisiert wird — erfordert ein paar einfache Praktiken.

1. Exakte Versionen in devDependencies festpinnen - verwenden Sie `"webpack": "5.88.2"` statt `"^5.88.0"` für build-kritische Tools. Schwebende Bereiche lassen Patches die installierte Version zwischen `npm install`-Läufen auf verschiedenen Maschinen ändern, was die Build-Ausgabe nicht-deterministisch macht.
2. Committen Sie Ihre Lockfile - `package-lock.json`, `yarn.lock` oder `pnpm-lock.yaml` müssen in die Versionskontrolle. Ohne sie installieren Beitragende und CI-Server unterschiedliche Patch-Versionen.
3. Version in CI protokollieren - fügen Sie vor jedem Build-Job einen `npx webpack --version`-Schritt hinzu. Die Version erscheint in jedem CI-Protokoll, was die Korrelation von Build-Fehlern mit Versionsänderungen erleichtert.
4. Abhängigkeiten nach Upgrades prüfen - wenn Sie Webpack aktualisieren, führen Sie sofort `npm list webpack --all` aus, um zu bestätigen, dass keine sekundären Kopien hineingeraten sind, und `npx webpack --version`, um zu bestätigen, dass die neue Version die ist, die Ihr Build verwendet.
5. Vor dem Upgrade die Migrationsanleitung lesen - jede Webpack-Major-Version hat eine offizielle Migrationsanleitung auf `webpack.js.org`. Lesen Sie sie vor dem Upgrade — nicht danach, wenn der Build bricht.