Vite

English

简体中文
日本語
Español
Português
한국어
Deutsch

English

简体中文
日本語
Español
Português
한국어
Deutsch

外觀

ViteConf Logo

共同建構

ViteConf 2024

觀看重播！

疑難排解 ​

另請參閱 Rollup 的疑難排解指南。

如果此處的建議無效，請嘗試在 GitHub Discussions 或 Vite Land Discord 的 #help 頻道上發問。

CJS ​

Vite CJS Node API 已棄用 ​

Vite 的 Node API 的 CJS 建構版本已棄用，並將在 Vite 6 中移除。請參閱 GitHub 討論以瞭解更多背景資訊。您應該更新您的檔案或框架，以改為匯入 Vite 的 ESM 建構版本。

在基本的 Vite 專案中，請確保

  1. vite.config.js 檔案內容使用 ESM 語法。
  2. 最接近的 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 標誌執行您的指令碼以記錄堆疊追蹤

bash
VITE_CJS_TRACE=true vite dev

如果您想暫時忽略警告，可以使用 VITE_CJS_IGNORE_WARNING=true 標誌執行您的指令碼

bash
VITE_CJS_IGNORE_WARNING=true vite dev

請注意，postcss 設定檔尚不支援 ESM + TypeScript (.mts 或 .ts 在 "type": "module" 中)。如果您的 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 ​

當使用 require 匯入僅限 ESM 的套件時，會發生以下錯誤。

無法解析「foo」。此套件僅為 ESM，但嘗試使用 require 載入。

Error [ERR_REQUIRE_ESM]: 不支援從 /path/to/vite.config.js 中的 require() 載入 ES Module /path/to/dependency.js。請改為將 /path/to/vite.config.js 中 index.js 的 require 變更為動態 import()，這在所有 CommonJS 模組中都可用。

在 Node.js <=22 中，預設情況下，無法使用 require 載入 ESM 檔案。

雖然使用 --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，您可能需要在 /etc/security/limits.conf 檔案中加入 * - nofile 65536 行，而不是更新 systemd 設定檔。

請注意，這些設定會持續存在，但需要重新啟動。

網路請求停止載入 ​

當使用自我簽署的 SSL 憑證時，Chrome 會忽略所有快取指令，並重新載入內容。Vite 依賴這些快取指令。

要解決此問題，請使用受信任的 SSL 憑證。

請參閱：快取問題、Chrome 問題

macOS ​

您可以使用此命令透過 CLI 安裝受信任的憑證

security add-trusted-cert -d -r trustRoot -k ~/Library/Keychains/login.keychain-db your-cert.cer

或者，將其匯入「鑰匙圈存取」應用程式，並將憑證的信任更新為「永遠信任」。

431 請求標頭欄位過大 ​

當伺服器/WebSocket 伺服器收到大型 HTTP 標頭時，將會捨棄請求，並顯示以下警告。

伺服器回應狀態碼 431。請參閱 https://vite.dev.org.tw/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 包含

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 通訊協定開啟，指令碼將無法執行，並出現以下錯誤。

已由 CORS 原則封鎖從來源「null」存取「file:///foo/bar.js」的指令碼：跨來源請求僅支援下列通訊協定配置：http、data、isolated-app、chrome-extension、chrome、https、chrome-untrusted。

已封鎖跨來源請求：相同來源原則不允許讀取 file:///foo/bar.js 的遠端資源。(原因：CORS 請求不是 http)。

請參閱 原因：CORS 請求不是 HTTP - HTTP | MDN 以瞭解有關為何會發生此情況的更多資訊。

您需要使用 http 通訊協定存取檔案。實現此目的的最簡單方法是執行 npx vite preview。

最佳化依賴項 ​

連結到本機套件時，預先綁定的依賴項已過時 ​

用於使優化後的依賴失效的雜湊金鑰取決於 package lock 檔案的內容、套用至依賴的修補程式，以及 Vite 組態檔中影響 Node 模組打包的選項。這表示當使用如 npm overrides 的功能覆寫依賴時，Vite 會偵測到，並在下次伺服器啟動時重新打包您的依賴。當您使用如 npm link 的功能時，Vite 不會使依賴失效。如果您連結或取消連結依賴，您需要在下次伺服器啟動時使用 vite --force 強制重新優化。我們建議改用 overrides，現在每個套件管理器都支援（另請參閱 pnpm overrides 和 yarn resolutions）。

效能瓶頸 ​

如果您遇到任何導致載入時間緩慢的應用程式效能瓶頸，您可以使用內建的 Node.js 檢查器啟動您的 Vite 開發伺服器或在建置應用程式時建立 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 內部始終是嚴格模式。

例如，您可能會看到這些錯誤。

[錯誤] 由於嚴格模式，無法將 with 語句與 "esm" 輸出格式一起使用

TypeError: 無法在布林值 'false' 上建立屬性 'foo'

如果這些程式碼在依賴中被使用，您可以使用 patch-package（或 yarn patch 或 pnpm patch）作為緊急措施。

瀏覽器擴充功能 ​

某些瀏覽器擴充功能（如廣告阻擋器）可能會阻止 Vite 客戶端將請求傳送至 Vite 開發伺服器。在這種情況下，您可能會看到空白畫面，而沒有記錄錯誤。如果您遇到此問題，請嘗試停用擴充功能。

如果您的 Windows 專案中有跨磁碟機連結，Vite 可能無法運作。

跨磁碟機連結的範例是

  • 使用 subst 命令連結到資料夾的虛擬磁碟機
  • 使用 mklink 命令連結到不同磁碟機的符號連結/接合點 (例如 Yarn 全域快取)

相關問題：#10802

在 MIT 授權下發布。(ccee3d7c)

版權所有 © 2019-present VoidZero Inc. & Vite Contributors