トラブルシューティング
さらなる情報はRollup のトラブルシューティングガイドもご覧ください。
こちらに提案されているもので動作しなかった場合、GitHub Discussions や Vite Land Discord の #help チャンネルで質問してみてください。
CJS
Vite の CJS Node API は非推奨に
Vite の Node API の CJS ビルドは非推奨となり、Vite 6 で削除される予定です。詳細は GitHub ディスカッションを参照してください。Vite の ESM ビルドをインポートするにはファイルやフレームワークを更新する必要があります。
基本的な Vite プロジェクトでは、以下を確認してください:
vite.config.jsファイルの内容が ESM 構文を使っていること- 最も近い
package.jsonファイルが"type": "module"を含むか、.mjs/.mts拡張子を利用すること（例：vite.config.mjsかvite.config.mts）
その他のプロジェクトについては、いくつかの一般的なアプローチがあります:
- ESM をデフォルトとして設定し、必要であれば CJS にオプトインする: プロジェクトの
package.jsonに"type": "module"を追加します。すべての*.jsファイルは ESM として解釈されるようになり、ESM 構文を使用する必要があります。ファイルの拡張子を.cjsにリネームすることで、CJS を使用し続けることができます。 - CJS をデフォルトのままにして、必要であれば ESM にオプトインする: プロジェクトの
package.jsonに"type": "module"がない場合、すべての*.jsファイルは CJS として解釈されます。ファイルの拡張子を.mjsにリネームすることで、ESM を使用できます。 - Vite を動的にインポートする: CJS を使用し続ける必要がある場合は、代わりに
import('vite')を使用して Vite を動的にインポートできます。これにはコードをasyncのコンテキストで記述する必要がありますが、Vite の API はほとんどが非同期であるため何とかなるでしょう。
警告の出所がわからない場合は、VITE_CJS_TRACE=true フラグを指定してスクリプトを実行し、スタックトレースを記録できます:
VITE_CJS_TRACE=true vite dev警告を一時的に無視したい場合は、VITE_CJS_IGNORE_WARNING=true フラグを指定してスクリプトを実行できます:
VITE_CJS_IGNORE_WARNING=true vite devなお、postcss の設定ファイルは ESM + TypeScript（"type": "module" の .mts や .ts）にはまだ対応していないので注意してください。もし、postcss の設定ファイルが .ts で、package.json に "type"： "module" を追加した場合、postcss の設定ファイル名を .cts に変更する必要があります。
CLI
Error: Cannot find module 'C:\foo\bar&baz\vite\bin\vite.js'
プロジェクトフォルダーへのパスに & が含まれているかもしれません。この場合、Windows では npm が動作しません（npm/cmd-shim#45）。
次のいずれかを行う必要があります:
- ほかのパッケージマネージャーに切り替える（例:
pnpm、yarn） - プロジェクトへのパスから
&を取り除く
設定
ESM のみのパッケージ
ESM のみのパッケージを require でインポートすると、以下のエラーが発生します。
Failed to resolve "foo". This package is ESM only but it was tried to load by
require.
Error [ERR_REQUIRE_ESM]: require() of ES Module /path/to/dependency.js from /path/to/vite.config.js not supported. Instead change the require of index.js in /path/to/vite.config.js to a dynamic import() which is available in all CommonJS modules.
Node.js 22 以前では、ESM ファイルはデフォルトでは require で読み込むことができません。
ESM ファイルは --experimental-require-module の利用や、Node.js 23 以降、その他のランタイムでは動作する可能性がありますが、まだ以下のいずれかの方法で、設定を ESM に変換することをお勧めします:
- 一番近い
package.jsonに"type": "module"を追加する vite.config.js/vite.config.tsをvite.config.mjs/vite.config.mtsにファイル名を変更する
開発サーバー
リクエストがいつまでも終わらない
Linux を利用している場合、ファイルディスクリプタ制限と inotify 制限が問題を引き起こしているかもしれません。Vite はほとんどのファイルをバンドルしないため、ブラウザーが大量のファイルをリクエストし、大量のファイルディスクリプタが必要になり、制限を超えることがあります。
これを解決するためには:
ulimitによりファイルディスクリプタ制限を引き上げるshell# 現在の制限を確認 $ ulimit -Sn # 制限を変更（一時的） $ ulimit -Sn 10000 # ハードリミットを変更する必要もあるかもしれません # ブラウザーを再起動するsysctlにより次の inotify 関連の制限を引き上げるshell# 現在の制限を確認 $ sysctl fs.inotify # 制限を変更（一時的） $ sudo sysctl fs.inotify.max_queued_events=16384 $ sudo sysctl fs.inotify.max_user_instances=8192 $ sudo sysctl fs.inotify.max_user_watches=524288
上記の手順でうまくいかない場合は、以下のファイルに DefaultLimitNOFILE=65536 をコメント無しで追加してみてください:
- /etc/systemd/system.conf
- /etc/systemd/user.conf
Ubuntu Linux では、systemd 設定ファイルを更新する代わりに、/etc/security/limits.conf のファイルに * - nofile 65536 という行を追加する必要があるかもしれません。
これらの設定は持続しますが、再起動が必要なことに注意してください。
ネットワークリクエストの読み込みが止まる
自己署名 SSL 証明書を使用する場合、Chrome はすべてのキャッシュディレクティブを無視し、コンテンツを再読み込みします。Vite は、これらのキャッシュディレクティブに依存しています。
この問題を解決するには、信頼できる SSL 証明書を使用してください。
参照: キャッシュの問題、Chrome の問題
macOS
このコマンドで、CLI から信頼できる証明書をインストールできます:
security add-trusted-cert -d -r trustRoot -k ~/Library/Keychains/login.keychain-db your-cert.cerまたは、キーチェーンアクセスアプリにインポートして、証明書の信頼度を「常に信頼」に更新します。
431 Request Header Fields Too Large
サーバー / WebSocket サーバーが大きな HTTP ヘッダーを受信した場合、リクエストが破棄され次のような警告が表示されます。
Server responded with status code 431. See https://vite.dev/guide/troubleshooting.html#_431-request-header-fields-too-large.
これは CVE-2018-12121 を軽減するため Node.js がリクエストヘッダーサイズを制限しているためです。
これを回避するためには、リクエストヘッダーサイズを減らすことを試みてください。例えば、クッキーが長い場合、削除します。あるいは、--max-http-header-size を利用して最大ヘッダーサイズを変更できます。
HMR
Vite がファイルの変更を検知しているのに HMR が動作しない
ファイルを別のケースでインポートしているかもしれません。例えば、src/foo.js が存在し、src/bar.js が次の内容を含んでいる場合:
import './Foo.js' // './foo.js' であるべき関連 issue: #964
Vite がファイル変更を検知しない
Vite を WSL2 で実行している場合、いくつかの条件下では Vite はファイル変更を監視できません。server.watch オプション を参照してください。
HMR ではなく完全なリロードが発生する
HMR が Vite またはプラグインによって処理されていない場合、状態を更新する唯一の方法であるため、フルリロードが行われます。
HMR が処理されているものの、それが循環依存関係の中にある場合、実行順序を回復するためにフルリロードも起こります。これを解決するには、そのループを解除してみてください。vite --debug hmr を実行することで、ファイル変更がトリガーとなった場合に、循環依存関係のパスをログに残すことができます。
ビルド
ビルドしたファイルが CORS エラーで動作しない
出力される HTML ファイルが file プロトコルで開かれている場合、以下のようなエラーでスクリプトが実行されません。
Access to script at 'file:///foo/bar.js' from origin 'null' has been blocked by CORS policy: Cross origin requests are only supported for protocol schemes: http, data, isolated-app, chrome-extension, chrome, https, chrome-untrusted.
Cross-Origin Request Blocked: The Same Origin Policy disallows reading the remote resource at file:///foo/bar.js. (Reason: CORS request not http).
この現象が発生する理由については、Reason: CORS request not HTTP - HTTP | MDN を参照してください。
ファイルには http プロトコルでアクセスする必要があります。これを実現する最も簡単な方法は、npx vite preview を実行することです。
最適化された依存関係
ローカルパッケージにリンクする際、事前バンドルした依存関係が古くなる
最適化された依存関係を無効にするために使用されるハッシュキーは、パッケージロックの内容、依存関係に適用されるパッチ、およびノードモジュールのバンドルに影響を与える Vite 設定ファイルのオプションに依存します。つまり、Vite は npm overrides のような機能を使って依存関係が上書きされたことを検出し、次のサーバー起動時に依存関係を再バンドルします。npm link のような機能を使っても、Vite は依存関係を無効化することはありません。依存関係をリンクまたはリンク解除した場合、次のサーバー起動時に vite --force を使って強制的に再最適化する必要があります。代わりにオーバーライドを使うことをお勧めします。オーバーライドは現在すべてのパッケージマネージャーでサポートされています（pnpm overrides および yarn resolutions も参照してください）。
パフォーマンスのボトルネック
アプリケーションのパフォーマンスがボトルネックとなり読み込みに時間がかかる場合、Vite 開発サーバーまたはアプリケーションをビルドするときに組み込みの Node.js インスペクターを起動して CPU プロファイルを作成できます:
vite --profile --openvite build --profileVite 開発サーバー
アプリケーションをブラウザーで開いたら、読み込みが終わるのを待ち、ターミナルに戻って p キーを押し（Node.js インスペクターを停止します）、次に q キーを押して開発サーバーを停止します。
Node.js インスペクターはルートフォルダーに vite-profile-0.cpuprofile を生成し、https://www.speedscope.app/ に遷移、BROWSE ボタンを使って CPU プロファイルをアップロードし、結果を検証します。
vite-plugin-inspect をインストールすると、Vite プラグインの中間状態を検査でき、アプリケーションのボトルネックとなっているプラグインやミドルウェアを特定するのに役立ちます。このプラグインは開発モードとビルドモードの両方で使用できます。詳しくは readme ファイルをご覧ください。
その他
ブラウザー互換性のためにモジュールを外部化
Node.js のモジュールをブラウザーで使用する場合、Vite では以下のような警告が出力されます。
Module "fs" has been externalized for browser compatibility. Cannot access "fs.readFile" in client code.
これは、Vite が Node.js のモジュールを自動的にポリフィルしないためです。
ポリフィルは手動で追加できますが、バンドルサイズを小さくするため、ブラウザーコードに Node.js モジュールを使うのは避けることをお勧めします。もし、モジュールが（ブラウザーで使用することを想定した）サードパーティのライブラリーからインポートされている場合は、それぞれのライブラリーに問題を報告することをお勧めします。
Syntax Error / Type Error が発生する
Vite は非厳格モード（sloppy モード）でのみ動作するコードを処理できず、対応していません。これは Vite が ESM を利用していて ESM 内では常に厳格モードであるためです。
例えば、次のようなエラーを表示されることがあります。
[ERROR] With statements cannot be used with the "esm" output format due to strict mode
TypeError: Cannot create property 'foo' on boolean 'false'
これらのコードが依存関係で使われていた場合、patch-package（または yarn patch または pnpm patch）をエスケープハッチとして利用できます。
ブラウザーの拡張機能
ブラウザーの拡張機能（広告ブロッカーなど）によっては、Vite クライアントが Vite 開発サーバーにリクエストを送信できなくすることがあります。この場合、白い画面が表示され、ログにはエラーが出力されません。この問題が発生した場合は、拡張機能を無効にしてみてください。
Windows のクロスドライブリンク
Windows でプロジェクトにクロスドライブリンクがある場合、Vite が動作しない場合があります。
クロスドライブリンクの例としては、以下のようなものがあります:
substコマンドでフォルダーにリンクされた仮想ドライブmklinkコマンドによる別ドライブへのシンボリックリンク/ジャンクション（例：Yarn のグローバルキャッシュ）
関連 issue: #10802