故障排除

另請參閱 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

當使用 require 匯入一個僅限 ESM 的包時，會出現以下錯誤。

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，你可能需要將 * - nofile 65536 行新增到 /etc/security/limits.conf 檔案中，而不是更新 systemd 配置檔案。

請注意，這些設定會永久生效，但需要重啟系統。

此外，如果伺服器在 VS Code 開發容器（devcontainer）中執行，請求可能會顯示為掛起。要修復此問題，請參閱 開發容器 / VS Code 埠轉發。

Vite 因 ENOSPC 錯誤而崩潰

如果你在 Linux 上看到如下錯誤：

Error: ENOSPC: System limit for number of file watchers reached

當專案目錄中的檔案過多（例如，大量的影像或資源）且超過了系統檔案監視器的限制時，會發生這種情況。Linux 的檔案監視器預設限制約為 8,192 到 10,000 個。

要解決此問題，你可以：

• 增加系統檔案監視器限制

  # Check current limit
  $ cat /proc/sys/fs/inotify/max_user_watches
  # Increase limit (temporary)
  $ sudo sysctl fs.inotify.max_user_watches=524288
  # Make it permanent - add to /etc/sysctl.conf (or edit if it already exists)
  $ echo "fs.inotify.max_user_watches=524288" | sudo tee -a /etc/sysctl.conf
  $ sudo sysctl -p

• 使用 server.watch.ignored 從檔案監視中排除檔案較多的目錄

• 使用 server.watch.usePolling 代替檔案系統事件進行輪詢。請注意，輪詢會佔用更多的 CPU 資源

網路請求停止載入

當使用自簽名 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.vuejs.tw/guide/troubleshooting.html#_431-request-header-fields-too-large。

這是因為 Node.js 限制了請求標頭的大小以緩解 CVE-2018-12121。

為避免此問題，請嘗試減小請求標頭的大小。例如，如果 Cookie 過長，請刪除它。或者，你可以使用 --max-http-header-size 來更改最大標頭大小。

開發容器 / VS Code 埠轉發

如果你正在使用 VS Code 中的開發容器或埠轉發功能，可能需要在配置中將 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 錯誤無法工作

如果使用 file 協議開啟 HTML 輸出檔案，指令碼將無法執行並出現以下錯誤。

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。

由於大小寫敏感導致“找不到檔案或目錄”錯誤

如果你遇到 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 檔案可能仍引用在舊版本中已被刪除的 chunk 名稱。這種情況發生在：

1. 使用者在瀏覽器中快取了舊版本的應用程式
2. 你部署了具有不同 chunk 名稱的新版本（由於程式碼更改）
3. 快取的 HTML 試圖載入不存在的 chunk

如果你使用的是框架，請先查閱其文件，因為它們可能已經有了針對此問題的內建解決方案。

要解決此問題，你可以：

• 暫時保留舊的 chunks：考慮將上一次部署的 chunks 保留一段時間，以便快取使用者能夠平穩過渡。
• 使用 Service Worker：實現一個 Service Worker 來預取並快取所有資源。
• 預取動態 chunks：請注意，如果你的 HTML 檔案由於 Cache-Control 標頭被瀏覽器快取，這可能無濟於事。
• 實現優雅的回退機制：為動態匯入實現錯誤處理，以便在 chunk 缺失時重新載入頁面。有關詳細資訊，請參閱 載入錯誤處理。

網路狀況不佳

此錯誤可能發生在不穩定的網路環境中。例如，當請求因網路錯誤或伺服器停機而失敗時。

請注意，由於瀏覽器限制，你無法重試動態匯入（whatwg/html#6768）。

瀏覽器擴充套件攔截請求

如果瀏覽器擴充套件（如廣告攔截器）阻止了請求，也可能發生此錯誤。

可以透過 build.rolldownOptions.output.chunkFileNames 選擇不同的 chunk 名稱來繞過此問題，因為這些擴充套件通常根據檔名攔截請求（例如包含 ad、track 的名稱）。

依賴項最佳化

連結本地包時預構建依賴項過時

用於廢棄已最佳化依賴項的雜湊鍵取決於包鎖檔案內容、應用於依賴項的補丁以及 Vite 配置檔案中影響 node_modules 打包的選項。這意味著 Vite 會檢測到何時使用類似 npm overrides 的功能覆蓋了依賴項，並在下次啟動伺服器時重新打包。當你使用類似 npm link 的功能時，Vite 不會廢棄這些依賴項。如果連結或取消連結了依賴項，你需要在下次啟動伺服器時透過 vite --force 強制重新最佳化。我們建議使用 overrides，目前所有包管理器都支援它（另請參閱 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 模組新增 Polyfill。

我們建議在瀏覽器程式碼中避免使用 Node.js 模組以減小打包體積，儘管你可以手動新增 Polyfill。如果該模組是從第三方庫（旨在在瀏覽器中使用）匯入的，建議向相應的庫報告此問題。

出現語法錯誤 / 型別錯誤

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 開發伺服器傳送請求。在這種情況下，你可能會看到白屏且沒有錯誤日誌。你也可能會看到以下錯誤：

TypeError: Failed to fetch dynamically imported module

如果遇到此問題，請嘗試停用擴充套件程式。

Windows 上的跨驅動器連結

如果你的專案在 Windows 上存在跨驅動器連結，Vite 可能無法正常工作。

跨驅動器連結的示例如下：

• 透過 subst 命令將虛擬驅動器連結到資料夾
• 透過 mklink 命令將符號連結/交接點連結到不同驅動器（例如 Yarn 全域性快取）

相關議題：#10802