トラブルシューティング

詳細については、Rollup のトラブルシューティングガイドも参照してください。

ここに記載されている提案がうまくいかない場合は、GitHub Discussions または Vite Land Discord の #help チャンネルで質問を投稿してみてください。

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 でロードできません。

--experimental-require-module を使用したり、Node.js >22 を使用したり、他のランタイムを使用したりすると機能する場合がありますが、次のいずれかの方法で設定を ESM に変換することをお勧めします。

• 最も近い package.json に "type": "module" を追加する
• vite.config.js/vite.config.ts を vite.config.mjs/vite.config.mts にリネームする

開発サーバー

リクエストが永久に停止する

Linux を使用している場合、ファイルディスクリプタの制限と inotify の制限が問題の原因となっている可能性があります。Vite はほとんどのファイルをバンドルしないため、ブラウザは多くのファイルディスクリプタを必要とする多くのファイルを要求し、制限を超過する可能性があります。

これを解決するには

• ulimit を使用してファイルディスクリプタの制限を増やす

  # Check current limit
  $ ulimit -Sn
  # Change limit (temporary)
  $ ulimit -Sn 10000 # You might need to change the hard limit too
  # Restart your browser

• sysctl を使用して以下の inotify 関連の制限を増やす

  # Check current limits
  $ sysctl fs.inotify
  # Change limits (temporary)
  $ 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 の行を追加する必要がある場合があります。

これらの設定は永続的ですが、**再起動が必要です**。

または、サーバーが VS Code Dev Container 内で実行されている場合、リクエストが停止しているように見えることがあります。この問題を解決するには、Dev Containers / VS Code ポート転送を参照してください。

ネットワークリクエストのロードが停止する

自己署名 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.dokyumento.jp/guide/troubleshooting.html#_431-request-header-fields-too-large.

これは、Node.js が CVE-2018-12121 を軽減するためにリクエストヘッダーサイズを制限しているためです。

これを回避するには、リクエストヘッダーのサイズを減らしてみてください。例えば、Cookie が長い場合は削除します。または、--max-http-header-size を使用して最大ヘッダーサイズを変更できます。

Dev Containers / VS Code ポート転送

VS Code で Dev Container またはポート転送機能を使用している場合、機能させるためには設定で server.host オプションを 127.0.0.1 に設定する必要があるかもしれません。

これは、VS Code のポート転送機能が IPv6 をサポートしていないためです。

詳細については、#16522 を参照してください。

HMR

Vite はファイル変更を検出するが HMR が機能しない

異なるケースのファイルをインポートしている可能性があります。例えば、src/foo.js が存在し、src/bar.js には以下が含まれます。

import './Foo.js' // should be './foo.js'

関連する問題: #964

Vite がファイル変更を検出しない

WSL2 で Vite を実行している場合、特定の条件下で Vite がファイル変更を監視できないことがあります。server.watch オプションを参照してください。

HMR の代わりにフルリロードが発生する

Vite またはプラグインによって HMR が処理されない場合、状態を更新する唯一の方法であるため、フルリロードが発生します。

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 のような機能を使用して依存関係が上書きされたことを検出し、次回のサーバー起動時に依存関係を再バンドルすることを意味します。Vite は npm link のような機能を使用した場合、依存関係を無効化しません。依存関係をリンクまたはリンク解除した場合、次回のサーバー起動時に vite --force を使用して強制的に再最適化する必要があります。現在ではすべてのパッケージマネージャーでサポートされている上書き機能の使用をお勧めします (参照: pnpm overrides および yarn resolutions)。

パフォーマンスのボトルネック

アプリケーションのパフォーマンスボトルネックが発生し、ロード時間が遅い場合は、Vite 開発サーバーを使用している場合、またはアプリケーションをビルドしている場合に、組み込みの Node.js インスペクターを起動して CPU プロファイルを生成できます。

開発サーバー

vite --profile --open

ビルド

vite build --profile

Vite 開発サーバー

ブラウザでアプリケーションが開いたら、ロードが完了するのを待ってから、ターミナルに戻り 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 モジュールを使用しないことをお勧めします。モジュールがサードパーティライブラリ (ブラウザで使用されることを意図したもの) からインポートされている場合は、それぞれのライブラリに問題を報告することをお勧めします。

構文エラー / 型エラーが発生する

Vite は非厳格モード (sloppy mode) でのみ実行されるコードを処理できず、サポートしていません。これは、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 グローバルキャッシュ)

関連する問題: #10802