docs(troubleshooting): add section for Failed to fetch dynamically imported module error

Author: jay-es

guide/build.md

@@ -78,7 +78,7 @@ window.addEventListener('vite:preloadError', (event) => {
 })
 ```
 
-新しいデプロイが行われると、ホスティングサービスは前回のデプロイからアセットを削除することがあります。その結果、新しいデプロイメントの前にあなたのサイトを訪れたユーザーがインポートエラーに遭遇してしまう可能性があります。このエラーが起こるのは、そのユーザーのデバイス上で実行されているアセットが古くなり、対応する削除された古いチャンクをインポートしようとしてしまうためです。このイベントは、このような状況に対処するのに便利です。
+新しいデプロイが行われると、ホスティングサービスは前回のデプロイからアセットを削除することがあります。その結果、新しいデプロイメントの前にあなたのサイトを訪れたユーザーがインポートエラーに遭遇してしまう可能性があります。このエラーが起こるのは、そのユーザーのデバイス上で実行されているアセットが古くなり、対応する削除された古いチャンクをインポートしようとしてしまうためです。このイベントは、このような状況に対処するのに便利です。この場合、HTML ファイルに `Cache-Control: no-cache` を設定してください。そうしないと古いアセットが参照され続けてしまいます。
 
 ## ファイル変更時のリビルド
 

guide/troubleshooting.md

@@ -150,6 +150,45 @@ HMR が処理されているものの、それが循環依存関係の中にあ
 
 `ENOENT: no such file or directory` や `Module not found` のようなエラーに遭遇した場合、これはプロジェクトが大文字と小文字を区別しないファイルシステム（Windows/macOS）で開発され、大文字と小文字を区別するファイルシステム（Linux）でビルドされたときによく発生します。インポートが正しい大文字と小文字を使用していることを確認してください。
 
+### `Failed to fetch dynamically imported module` エラー
+
+> TypeError: Failed to fetch dynamically imported module
+
+このエラーはいくつかのケースで発生します:
+
+- バージョンの不一致
+- ネットワーク環境の悪化
+- ブラウザー拡張によるリクエストのブロック
+
+#### バージョンの不一致
+
+アプリケーションの新しいバージョンをデプロイした時、HTML ファイルと JS ファイルは新しいデプロイメントで削除された古いチャンク名を参照し続けます。これは以下の場合に発生します:
+
+1. ユーザーのブラウザーに古いバージョンのアプリがキャッシュされている
+2. 異なるチャンク名を持つ新しいバージョンをデプロイした（コード変更による）
+3. キャッシュされた HTML が、もう存在しないチャンクを読み込もうとする
+
+フレームワークを使用している場合は、この問題に対する組み込みのソリューションがあるかもしれませんので、まずそちらのドキュメントを参照してください。
+
+これを解決するために、以下のことができます:
+
+- **古いチャンクを一時的に保持する**: キャッシュされたユーザーがスムーズに移行できるよう、前回のデプロイメントのチャンクを一定期間保持することを検討してください。
+- **サービスワーカーを使用する**: すべてのアセットを事前取得してキャッシュするサービスワーカーを実装してください。
+- **動的チャンクを事前取得する**: `Cache-Control` ヘッダーにより HTML ファイルがブラウザーにキャッシュされている場合、これは役に立たないことに注意してください。
+- **グレースフルフォールバックを実装する**: チャンクが見つからない場合にページをリロードするよう、動的インポートにエラーハンドリングを実装してください。詳細は[読み込みエラーハンドリング](./build.md#load-error-handling)を参照してください。
+
+#### ネットワーク環境の悪化
+
+このエラーは不安定なネットワーク環境で発生する可能性があります。例えば、ネットワークエラーやサーバーダウンタイムによりリクエストが失敗した場合です。
+
+ブラウザーの制限により、動的インポートを再試行することはできないことに注意してください（[whatwg/html#6768](https://github.com/whatwg/html/issues/6768)）。
+
+#### ブラウザー拡張によるリクエストのブロック
+
+ブラウザー拡張（広告ブロッカーなど）がそのリクエストをブロックしている場合にもエラーが発生することがあります。
+
+これらの拡張機能はファイル名に基づいてリクエストをブロックすることが多いため（例: `ad`、`track` を含む名前）、[`build.rollupOptions.output.chunkFileNames`](../config/build-options.md#build-rollupoptions)で異なるチャンク名を選択することで回避できる可能性があります。
+
 ## 最適化された依存関係
 
 ### ローカルパッケージにリンクする際、事前バンドルした依存関係が古くなる
@@ -206,7 +245,11 @@ Vite は非厳格モード（sloppy モード）でのみ動作するコード
 
 ### ブラウザーの拡張機能
 
-ブラウザーの拡張機能（広告ブロッカーなど）によっては、Vite クライアントが Vite 開発サーバーにリクエストを送信できなくすることがあります。この場合、白い画面が表示され、ログにはエラーが出力されません。この問題が発生した場合は、拡張機能を無効にしてみてください。
+ブラウザーの拡張機能（広告ブロッカーなど）によっては、Vite クライアントが Vite 開発サーバーにリクエストを送信できなくすることがあります。この場合、白い画面が表示され、ログにはエラーが出力されません。また、以下のようなエラーが表示されることもあります:
+
+> TypeError: Failed to fetch dynamically imported module
+
+この問題が発生した場合は、拡張機能を無効にしてみてください。
 
 ### Windows のクロスドライブリンク