Fehlerbehebung

Siehe Rollup-Fehlerbehebungshandbuch für weitere Informationen.

Wenn die hier vorgeschlagenen Lösungen nicht funktionieren, versuchen Sie, Ihre Fragen in GitHub-Diskussionen zu posten oder im #help-Kanal von Vite Land Discord zu stellen.

Befehlszeilenschnittstelle (CLI)

Fehler: Modul 'C:\foo\bar&baz\vite\bin\vite.js' nicht gefunden

Der Pfad zu Ihrem Projektverzeichnis kann ein & enthalten, was unter Windows nicht mit npm funktioniert (npm/cmd-shim#45).

Sie müssen entweder:

• Zu einem anderen Paketmanager wechseln (z.B. pnpm, yarn)
• Entfernen Sie das & aus dem Pfad zu Ihrem Projekt

Konfiguration

Dieses Paket ist nur für ESM (ECMAScript Module) geeignet

Beim Importieren eines ESM-Pakets nur über require tritt der folgende Fehler auf:

Fehlgeschlagen, um "foo" aufzulösen. Dieses Paket ist nur für ESM geeignet, wurde jedoch versucht, über require geladen zu werden.

Fehler [ERR_REQUIRE_ESM]: require() des ES-Moduls /path/to/dependency.js aus /path/to/vite.config.js wird nicht unterstützt. Ändern Sie stattdessen das require von index.js in /path/to/vite.config.js in einen dynamischen import(), der in allen CommonJS-Modulen verfügbar ist.

In Node.js <=22 können ESM-Dateien standardmäßig nicht mit require geladen werden.

Obwohl dies mit --experimental-require-module oder Node.js >22 oder in anderen Laufzeitumgebungen funktionieren kann, empfehlen wir dennoch, Ihre Konfiguration entweder durch:

• "type": "module" zum nächsten package.json hinzufügen
• vite.config.js/vite.config.ts in vite.config.mjs/vite.config.mts umbenennen

Entwicklungsserver

Anfragen sind dauerhaft blockiert

Wenn Sie Linux verwenden, können Begrenzungen für Dateideskriptoren und Inotify-Begrenzungen das Problem verursachen. Da Vite die meisten Dateien nicht bündelt, können Browser viele Dateien anfordern, die viele Dateideskriptoren erfordern und die Grenze überschreiten.

Um dies zu lösen:

• Erhöhen Sie die Begrenzung für Dateideskriptoren mit ulimit

  # Aktuelle Begrenzung überprüfen
  $ ulimit -Sn
  # Begrenzung ändern (vorübergehend)
  $ ulimit -Sn 10000 # Möglicherweise müssen Sie die harte Begrenzung ebenfalls ändern
  # Starten Sie Ihren Browser neu

• Erhöhen Sie die folgenden Inotify-bezogenen Begrenzungen mit sysctl

  # Aktuelle Begrenzungen überprüfen
  $ sysctl fs.inotify
  # Begrenzungen ändern (vorübergehend)
  $ sudo sysctl fs.inotify.max_queued_events=16384
  $ sudo sysctl fs.inotify.max_user_instances=8192
  $ sudo sysctl fs.inotify.max_user_watches=524288

Wenn die oben genannten Schritte nicht funktionieren, können Sie DefaultLimitNOFILE=65536 als auskommentierte Konfiguration in den folgenden Dateien hinzufügen:

• /etc/systemd/system.conf
• /etc/systemd/user.conf

Für Ubuntu Linux müssen Sie möglicherweise die Zeile * - nofile 65536 anstelle der Aktualisierung der systemd-Konfigurationsdateien in die Datei /etc/security/limits.conf hinzufügen.

Beachten Sie, dass diese Einstellungen bestehen bleiben, aber ein Neustart erforderlich ist.

Wenn der Server in einem VS Code-Entwicklungscontainer ausgeführt wird, kann es vorkommen, dass die Anfrage scheinbar zum Stillstand gekommen ist. Um dieses Problem zu beheben, lesen Sie Entwicklungscontainer / VS Code-Portweiterleitung.

Netzwerkanfragen werden nicht geladen

Wenn Sie ein selbstsigniertes SSL-Zertifikat verwenden, ignoriert Chrome alle Cache-Anweisungen und lädt den Inhalt neu. Vite ist auf diese Cache-Anweisungen angewiesen.

Um das Problem zu lösen, verwenden Sie ein vertrauenswürdiges SSL-Zertifikat.

Siehe: Cache-Probleme, Chrome-Fehler

macOS

Sie können ein vertrauenswürdiges Zertifikat über die Befehlszeile mit diesem Befehl installieren:

security add-trusted-cert -d -r trustRoot -k ~/Library/Keychains/login.keychain-db your-cert.cer

Oder Sie importieren es in die Keychain Access-App und aktualisieren das Vertrauen in Ihr Zertifikat auf "Immer vertrauen".

431 Request Header Fields Too Large

Wenn der Server / WebSocket-Server einen großen HTTP-Header erhält, wird die Anforderung verworfen, und die folgende Warnung wird angezeigt.

Der Server hat mit dem Statuscode 431 geantwortet. Siehe https://vite.dev/guide/troubleshooting.html#_431-request-header-fields-too-large.

Dies liegt daran, dass Node.js die Größe des Anforderungshauptkopfs begrenzt, um CVE-2018-12121 zu verhindern.

Um dies zu vermeiden, versuchen Sie, die Größe des Anforderungshauptkopfs zu reduzieren. Wenn beispielsweise der Cookie lang ist, löschen Sie ihn. Oder Sie können --max-http-header-size verwenden, um die maximale Headergröße zu ändern.

Dev Containers / VS Code Port Forwarding

Wenn Sie einen Dev-Container oder die Portweiterleitung in VS Code benutzen, kann es sein, dass sie die server.host Option mit 127.0.0.1 in der Konfiguration setzen müssen.

Der Grund dafür ist, dass die Portweiterleitung in VS Code kein IPv6 unterstützt.

Siehe #16522 für mehr Details.

HMR (Hot Module Replacement)

Vite erkennt eine Dateiänderung, aber das HMR funktioniert nicht

Es kann sein, dass Sie eine Datei mit einer anderen Groß-/Kleinschreibung importieren. Zum Beispiel existiert src/foo.js und `src/bar.js

` enthält:

import './Foo.js' // sollte './foo.js' sein

Verwandtes Problem: #964

Vite erkennt keine Dateiänderung

Wenn Sie Vite mit WSL2 ausführen, kann Vite in bestimmten Situationen keine Dateiänderungen überwachen. Siehe server.watch-Option.

Es erfolgt eine vollständige Aktualisierung anstelle von HMR

Wenn HMR nicht von Vite oder einem Plugin behandelt wird, erfolgt eine vollständige Seitenaktualisierung, da dies die einzige Möglichkeit ist, den Status zu aktualisieren.

Wenn HMR bedient wird, aber in einer zirkulären Abhängigkeit steht, wird ebenfalls eine vollständige Seitenaktualisierung durchgeführt, um die Ausführungsreihenfolge wiederherzustellen. Um dieses Problem zu lösen, versuchen Sie, die Schleife zu unterbrechen. Sie können vite --debug hmr ausführen, um den Pfad der zirkulären Abhängigkeit zu protokollieren, wenn eine Dateiänderung dies ausgelöst hat.

Build

Die generierte Datei funktioniert aufgrund eines CORS-Fehlers nicht

Wenn die HTML-Dateiausgabe mit dem file-Protokoll geöffnet wurde, werden die Skripte mit dem folgenden Fehler nicht ausgeführt.

Der Zugriff auf das Skript unter 'file:///foo/bar.js' von der Herkunft 'null' wurde durch die CORS-Richtlinie blockiert: Nur Protokollschemata http, data, isolated-app, chrome-extension, chrome, https, chrome-untrusted werden für Cross-Origin-Anfragen unterstützt.

Cross-Origin-Anfrage blockiert: Die Same-Origin-Richtlinie untersagt das Lesen der entfernten Ressource unter 'file:///foo/bar.js'. (Grund: CORS-Anforderung nicht http).

Sie müssen auf die Datei mit dem http-Protokoll zugreifen. Der einfachste Weg, dies zu erreichen, ist das Ausführen von npx vite preview.

ENOENT: no such file or directory-Fehler Grund von Groß-/Kleinschreibung

Falls Sie Fehlern wie ENOENT: no such file or directory oder Module not found begegnen, liegt es oft daran, dass Ihr Projekt auf einem System entwickelt wurde, welches nicht zwischen Groß- und Kleinschreibung unterscheidet (Windows / macOS) und anschließend auf einem System gebaut wurde, dass Groß-/Kleinschreibung berücksichtigt (Linux). Bitte stellen Sie sicher, dass die Importe die korrekte Schreibweise haben.

Optimisierte Abhängigkeiten

Failed to fetch dynamically imported module Fehler

TypeError: Failed to fetch dynamically imported module

Dieser Fehler tritt in mehreren Fällen auf:

• Versionsunterschiede
• Schlechte Netzwerkbedingungen
• Browser-Erweiterungen, die Anfragen blockieren

Versionsunterschiede

Wenn Sie eine neue Version Ihrer Anwendung bereitstellen, verweisen die HTML-Datei und die JS-Dateien weiterhin auf alte Chunk-Namen, die in der neuen Bereitstellung gelöscht wurden. Dies geschieht, wenn:

1. Benutzer eine alte Version Ihrer App in ihrem Browser zwischengespeichert haben.
2. Sie eine neue Version mit anderen Chunk-Namen bereitstellen (aufgrund von Codeänderungen)
3. Die zwischengespeicherte HTML-Datei versucht, Chunks zu laden, die nicht mehr existieren.

Wenn Sie ein Framework verwenden, lesen Sie zunächst dessen Dokumentation, da es möglicherweise eine integrierte Lösung für dieses Problem enthält.

Um dieses Problem zu beheben, haben Sie folgende Möglichkeiten:

• Alte Chunks vorübergehend beibehalten: Erwägen Sie, die Chunks der vorherigen Bereitstellung für einen bestimmten Zeitraum beizubehalten, um Benutzern mit zwischengespeicherten Daten einen reibungslosen Übergang zu ermöglichen.
• Verwenden Sie einen Service Worker: Implementieren Sie einen Service Worker, der alle Assets vorab abruft und zwischenspeichert.
• Rufen Sie die dynamischen Chunks vorab ab: Beachten Sie, dass dies nicht hilft, wenn Ihre HTML-Datei aufgrund von Cache-Control-Headern vom Browser zwischengespeichert wird.
• Implementieren Sie einen eleganten Fallback: Implementieren Sie eine Fehlerbehandlung für dynamische Importe, um die Seite neu zu laden, wenn Chunks fehlen. Weitere Informationen finden Sie unter Fehlerbehandlung beim Laden.

Schlechte Netzwerkbedingungen

Dieser Fehler kann in instabilen Netzwerkumgebungen auftreten. Beispielsweise wenn die Anfrage aufgrund von Netzwerkfehlern oder Serverausfällen fehlschlägt.

Beachten Sie, dass Sie den dynamischen Import aufgrund von Browserbeschränkungen (whatwg/html#6768) nicht wiederholen können.

Browser-Erweiterungen, die Anfragen blockieren

Der Fehler kann auch auftreten, wenn Browser-Erweiterungen (wie Werbeblocker) diese Anfrage blockieren.

Möglicherweise lässt sich das Problem umgehen, indem Sie einen anderen Chunk-Namen unter build.rollupOptions.output.chunkFileNames auswählen, da diese Erweiterungen Anfragen häufig anhand von Dateinamen blockieren (z. B. Namen, die „ad“ oder „track“ enthalten).

Veraltete vorbündelte Abhängigkeiten bei Verknüpfung mit einem lokalen Paket

Der Hash-Wert, der zum Ungültigmachen optimierter Abhängigkeiten verwendet wird, hängt von den Inhalten des Paketsperrverzeichnisses, den auf Abhängigkeiten angewendeten Patches und den Optionen in der Vite-Konfigurationsdatei ab, die sich auf das Bündeln von Node-Modulen auswirken. Dies bedeutet, dass Vite erkennt, wenn eine Abhängigkeit mit einer Funktion wie npm overrides überschrieben wird, und Ihre Abhängigkeiten beim nächsten Serverstart erneut bündelt. Vite wird die Abhängigkeiten nicht ungültig machen, wenn Sie eine Funktion wie npm link verwenden. Wenn Sie eine Abhängigkeit verknüpfen oder entknüpfen, müssen Sie beim nächsten Serverstart eine erneute Optimierung erzwingen, indem Sie vite --force verwenden. Wir empfehlen stattdessen die Verwendung von Überschreibungen, die jetzt von jedem Paketmanager unterstützt werden (siehe auch pnpm overrides und yarn resolutions).

Der Hash-Schlüssel, der zum Ungültigmachen optimierter Abhängigkeiten verwendet wird, hängt vom Inhalt der Paketsperre, den auf die Abhängigkeiten angewendeten Patches und den Optionen in der Vite-Konfigurationsdatei ab, die sich auf die Bündelung von Node-Modulen auswirken. Das bedeutet, dass Vite erkennt, wenn eine Abhängigkeit mit einer Funktion wie npm overrides überschrieben wird, und Ihre Abhängigkeiten beim nächsten Serverstart neu bündelt. Vite wird die Abhängigkeiten nicht ungültig machen, wenn Sie eine Funktion wie npm link verwenden. Falls Sie eine Abhängigkeit verlinken oder aufheben, müssen Sie beim nächsten Serverstart eine erneute Optimierung erzwingen, indem Sie vite --force verwenden. Wir empfehlen stattdessen die Verwendung von Overrides, die mittlerweile von jedem Paketmanager unterstützt werden (siehe auch pnpm overrides und yarn resolutions).

Leistungsengpässe

Wenn Sie unter Leistungsengpässen Ihrer Anwendung leiden, die zu langen Ladezeiten führen, können Sie den integrierten Node.js-Inspector mit Ihrem Vite-Entwicklungsserver oder beim Erstellen Ihrer Anwendung starten, um das CPU-Profil zu erstellen:

dev server

vite --profile --open

build

vite build --profile

Vite Dev Server

Sobald Ihre Anwendung im Browser geöffnet ist, warten Sie, bis sie fertig geladen ist, und kehren Sie dann zum Terminal zurück und drücken Sie die Taste p (um den Node.js-Inspektor zu stoppen), drücken Sie dann die Taste q, um den Entwicklungsserver zu stoppen.

Der Node.js-Inspektor erstellt ein CPU-Profil mit dem Namen vite-profile-0.cpuprofile im Stammverzeichnis. Gehen Sie zu https://www.speedscope.app/ und laden Sie das CPU-Profil mit der Schaltfläche BROWSE hoch, um das Ergebnis zu überprüfen.

Sie können vite-plugin-inspect installieren, mit dem Sie den Zwischenzustand von Vite-Plugins inspizieren und identifizieren können, welche Plugins oder Middleware in Ihren Anwendungen Engpässe darstellen. Das Plugin kann sowohl im Entwicklungs- als auch im Build-Modus verwendet werden. Weitere Details finden Sie in der Readme-Datei.

Sonstiges

Modul für die Browserkompatibilität externalisiert

Wenn Sie ein Node.js-Modul im Browser verwenden, gibt Vite die folgende Warnung aus.

Das Modul "fs" wurde für die Browserkompatibilität externalisiert. Kann "fs.readFile" im Clientcode nicht verwenden.

Dies liegt daran, dass Vite Node.js-Module nicht automatisch polyfällt.

Wir empfehlen, Node.js-Module für Browsercode zu vermeiden, um die Bündelgröße zu reduzieren. Sie können jedoch Polyfills manuell hinzufügen. Wenn das Modul aus einer Drittanbieter-Bibliothek importiert wird (die für die Verwendung im Browser vorgesehen ist), wird empfohlen, das Problem an die entsprechende Bibliothek zu melden.

Syntaxfehler / Typfehler tritt auf

Vite kann Code, der nur im nicht-strikten Modus (sloppy mode) ausgeführt wird, nicht verarbeiten und unterstützt ihn nicht. Dies liegt daran, dass Vite ESM verwendet und innerhalb von ESM immer im strikten Modus ausgeführt wird.

Beispielsweise könnten Sie diese Fehler sehen.

[ERROR] With statements cannot be used with the "esm" output format due to strict mode

TypeError: Cannot create property 'foo' on boolean 'false'

Wenn diese Codes innerhalb von Abhängigkeiten verwendet werden, können Sie patch-package (oder yarn patch oder pnpm patch) als Ausweg verwenden.

Browsererweiterungen

Einige Browser-Erweiterungen (wie Werbeblocker) können verhindern, dass der Vite-Client Anfragen an den Vite-Entwicklungsserver sendet. In diesem Fall wird möglicherweise ein weißer Bildschirm ohne protokollierte Fehler angezeigt. Möglicherweise wird auch der folgende Fehler angezeigt:

TypeError: Failed to fetch dynamically imported module

Deaktivieren Sie die Erweiterungen, wenn dieses Problem auftritt.

Verknüpfungen zwischen verschiedenen Laufwerken in Windows

Wenn es in Ihrem Projekt unter Windows Verknüpfungen zwischen verschiedenen Laufwerken gibt, funktioniert Vite möglicherweise nicht.

Beispiele für Verknüpfungen zwischen verschiedenen Laufwerken sind:

• Ein virtuelles Laufwerk, das über den subst-Befehl mit einem Ordner verknüpft ist
• Ein Symlink/Junction zu einem anderen Laufwerk über den mklink-Befehl (z.B. Yarn Global Cache)

Verwandtes Problem: #10802