トラブルシューティング

詳細については、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 として解釈されます。代わりに ESM を使用するには、ファイルを .mjs 拡張子で名前変更できます。
Vite を動的にインポートする: CJS を使用し続ける必要がある場合は、代わりに import('vite') を使用して Vite を動的にインポートできます。これにより、コードを async コンテキストで記述する必要がありますが、Vite の API はほとんどが非同期であるため、管理可能です。

警告がどこから来ているのかわからない場合は、VITE_CJS_TRACE=true フラグを付けてスクリプトを実行して、スタックトレースをログに記録できます。

bash

VITE_CJS_TRACE=true vite dev

一時的に警告を無視したい場合は、VITE_CJS_IGNORE_WARNING=true フラグを付けてスクリプトを実行できます。

bash

VITE_CJS_IGNORE_WARNING=true vite dev

postcss 設定ファイルは、ESM + TypeScript（"type": "module" 内の .mts または .ts）をまだサポートしていないことに注意してください。.ts を使用した postcss 設定があり、package.json に "type": "module" を追加した場合は、postcss 設定を .cts を使用するように名前変更する必要があります。

CLI

`エラー：モジュール 'C:\foo\bar&baz\vite\bin\vite.js' が見つかりません`

プロジェクトフォルダーへのパスに & が含まれている可能性があります。これは Windows 上の npm では機能しません（npm/cmd-shim#45）。

次のいずれかを行う必要があります。

別のパッケージマネージャー（例：pnpm、yarn）に切り替えます。
プロジェクトへのパスから & を削除します。

設定

このパッケージは ESM のみです

require によって ESM のみのパッケージをインポートすると、次のエラーが発生します。

「foo」を解決できませんでした。このパッケージは ESM のみですが、require でロードしようとしました。

エラー [ERR_REQUIRE_ESM]: /path/to/vite.config.js からの /path/to/dependency.js の ES Module の require() はサポートされていません。代わりに、/path/to/vite.config.js での index.js の require を、すべての CommonJS モジュールで使用できる動的な import() に変更してください。

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 でファイル記述子の制限を増やします。

shell

# 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 関連の制限を増やします。

shell

# 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 という行を追加する必要がある場合があります。

これらの設定は持続しますが、再起動が必要です。

ネットワークリクエストの読み込みが停止する

自己署名 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 ヘッダーを受信すると、リクエストはドロップされ、次の警告が表示されます。

サーバーがステータスコード 431 で応答しました。https://vite.dokyumento.jp/guide/troubleshooting.html#_431-request-header-fields-too-large を参照してください。

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

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

HMR

Vite がファイル変更を検出しても HMR が機能しない

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

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

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

WSL2 で Vite を実行している場合、Vite は特定の状況でファイル変更を監視できません。server.watch オプションを参照してください。

HMR の代わりに完全なリロードが発生する

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

HMR が処理されているが、循環依存関係内にある場合、実行順序を回復するために完全なリロードも発生します。これを解決するには、ループを中断してみてください。ファイル変更によって循環依存関係がトリガーされた場合、vite --debug hmr を実行して循環依存関係のパスをログに記録できます。

ビルド

CORS エラーのためにビルドされたファイルが機能しない

出力された HTML ファイルが file プロトコルで開かれた場合、スクリプトは次のエラーで実行されません。

オリジン「null」からの「file:///foo/bar.js」にあるスクリプトへのアクセスは、CORS ポリシーによってブロックされました。クロスオリジンリクエストは、プロトコルスキームが http、data、isolated-app、chrome-extension、chrome、https、chrome-untrusted の場合にのみサポートされます。

クロスオリジンリクエストがブロックされました：同一オリジンポリシーにより、file:///foo/bar.jsにあるリモートリソースの読み込みが許可されません。（理由：CORSリクエストが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プロファイルを作成できます。

開発サーバービルド

bash

vite --profile --open

bash

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は次の警告を出力します。

モジュール "fs" はブラウザ互換性のために外部化されました。クライアントコードで "fs.readFile" にアクセスできません。

これは、ViteがNode.jsモジュールを自動的にポリフィルしないためです。

バンドルサイズを小さくするために、ブラウザコードでNode.jsモジュールを避けることをお勧めします。ただし、手動でポリフィルを追加することもできます。モジュールが（ブラウザで使用されることを意図した）サードパーティライブラリからインポートされている場合は、それぞれのライブラリに問題を報告することをお勧めします。

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

Viteは、非厳格モード（スロッピーモード）でのみ実行されるコードを処理およびサポートしません。これは、ViteがESMを使用しており、ESM内では常に厳格モードであるためです。

たとえば、次のエラーが表示される場合があります。

[ERROR] strict modeのため、"esm" 出力形式ではWithステートメントを使用できません

TypeError: boolean 'false' にプロパティ 'foo' を作成できません

これらのコードが依存関係内で使用されている場合は、patch-package（またはyarn patchまたはpnpm patch）を回避策として使用できます。

ブラウザ拡張機能

一部のブラウザ拡張機能（広告ブロッカーなど）は、ViteクライアントがVite開発サーバーにリクエストを送信するのを妨げる可能性があります。この場合、エラーがログに記録されずに白い画面が表示される場合があります。この問題が発生した場合は、拡張機能を無効にしてみてください。

Windowsでのクロスドライブリンク

Windowsでプロジェクト内にクロスドライブリンクがある場合、Viteが機能しない可能性があります。

クロスドライブリンクの例は次のとおりです。

substコマンドでフォルダーにリンクされた仮想ドライブ
mklinkコマンドで異なるドライブへのシンボリックリンク/ジャンクション（例：Yarnグローバルキャッシュ）

トラブルシューティング ​

CJS ​

Vite CJS Node API の非推奨 ​

CLI ​

エラー：モジュール 'C:\foo\bar&baz\vite\bin\vite.js' が見つかりません ​

設定 ​

このパッケージは ESM のみです ​

開発サーバー ​

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

ネットワークリクエストの読み込みが停止する ​

macOS ​

431 Request Header Fields Too Large ​

HMR ​

Vite がファイル変更を検出しても HMR が機能しない ​

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

HMR の代わりに完全なリロードが発生する ​

ビルド ​

CORS エラーのためにビルドされたファイルが機能しない ​

最適化された依存関係 ​

ローカルパッケージへのリンク時に古いプリバンドルされた依存関係が発生する ​

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

その他 ​

ブラウザ互換性のためにモジュールが外部化されました ​

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

ブラウザ拡張機能 ​

Windowsでのクロスドライブリンク ​

トラブルシューティング

CJS

Vite CJS Node API の非推奨

CLI

`エラー：モジュール 'C:\foo\bar&baz\vite\bin\vite.js' が見つかりません`

設定

このパッケージは ESM のみです

開発サーバー

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

ネットワークリクエストの読み込みが停止する

macOS

431 Request Header Fields Too Large

HMR

Vite がファイル変更を検出しても HMR が機能しない

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

HMR の代わりに完全なリロードが発生する

ビルド

CORS エラーのためにビルドされたファイルが機能しない

最適化された依存関係

ローカルパッケージへのリンク時に古いプリバンドルされた依存関係が発生する

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

その他

ブラウザ互換性のためにモジュールが外部化されました

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

ブラウザ拡張機能

Windowsでのクロスドライブリンク