故障排除?

你還可以查看 Rollup 的故障排除指南 了解更多。

如果這里的建議并未幫助到你，請(qǐng)將你的問題發(fā)送到 GitHub 討論區(qū) 或 Vite Land Discord 的 #help 頻道。

CLI?

Error: Cannot find module 'C:\foo\bar&baz\vite\bin\vite.js'?

你的項(xiàng)目文件夾路徑中可能包含了符號(hào) &，這在 Windows 上無法與 npm 配合正常工作 (npm/cmd-shim#45)。

你可以選擇以下兩種修改方式：

• 切換另一種包管理工具（例如 pnpm 或 yarn）
• 從你的項(xiàng)目路徑中移除符號(hào) &

開發(fā)服務(wù)器?

請(qǐng)求始終停滯?

如果你使用的是 Linux，文件描述符限制和 inotify 限制可能會(huì)導(dǎo)致這個(gè)問題。由于 Vite 不會(huì)打包大多數(shù)文件，瀏覽器可能會(huì)請(qǐng)求許多文件，而相應(yīng)地需要許多文件描述符，因此超過了限制。

要解決這個(gè)問題：

• 使用 ulimit 增加文件描述符的限制

  shell

  # 查看當(dāng)前限制值
  $ ulimit -Sn
  # （暫時(shí)）更改限制值
  $ ulimit -Sn 10000 # 你可能也需要更改硬性限制值
  # 重啟你的瀏覽器
  
  

• 通過 sysctl 提升下列 inotify 相關(guān)的限制

  shell

  # 查看當(dāng)前限制值
  $ sysctl fs.inotify
  # （暫時(shí)）更改限制值
  $ 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

對(duì)于 Ubuntu Linux 操作系統(tǒng)，你可能需要添加一行 * - nofile 65536 到文件 /etc/security/limits.conf 之中，而不是更新 systemd 配置文件。

請(qǐng)注意，這些配置會(huì)持久作用，但需要 重新啟動(dòng)。

網(wǎng)絡(luò)請(qǐng)求停止加載?

使用自簽名SSL證書時(shí)，Chrome 會(huì)忽略所有緩存指令并重新加載內(nèi)容。而 Vite 依賴于這些緩存指令。

要解決此問題，請(qǐng)使用受信任的SSL證書。

請(qǐng)查看：緩存問題 和相關(guān)的 Chrome issue

macOS?

您可以使用以下命令通過 CLI 安裝受信任的證書：

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

或者，通過將其導(dǎo)入 Keychain Access 應(yīng)用程序并將您的證書的信任更新為“始終信任”。

431 Request Header Fields Too Large?

當(dāng)服務(wù)器或 WebSocket 服務(wù)收到一個(gè)較大的 HTTP 頭，該請(qǐng)求可能會(huì)被遺落并且會(huì)顯示下面這樣的警告。

Server responded with status code 431. See https://vitejs.dev/guide/troubleshooting.html#_431-request-header-fields-too-large.

這是由于 Node.js 限制請(qǐng)求頭大小，以減輕 CVE-2018-12121 的影響。

要避免這個(gè)問題，請(qǐng)嘗試減小請(qǐng)求頭大小。舉個(gè)例子，如果 cookie 太長，請(qǐng)刪除它?；蛘吣憧梢允褂?--max-http-header-size 來更改最大請(qǐng)求頭大小。

HMR?

Vite 檢測到文件變化，但 HMR 不工作?

你可能導(dǎo)入了一個(gè)擁有不同大小寫的文件，例如，存在 src/foo.js 文件而 src/bar.js 導(dǎo)入了它：

js

import './Foo.js' // 應(yīng)該為 './foo.js'

相關(guān) issue：#964

Vite 沒有檢測到文件變化?

如果你正在 WSL2 中運(yùn)行 Vite，Vite 無法在某些場景下監(jiān)聽文件變化。請(qǐng)查看 server.watch 選項(xiàng) 的描述。

完全重新加載了，而不是 HMR?

如果 HMR 不是由 Vite 或一個(gè)插件處理的，那么將進(jìn)行完全的重新加載。

同時(shí)如果有依賴環(huán)，也會(huì)發(fā)生完全重載。要解決這個(gè)問題，請(qǐng)先嘗試解決依賴循環(huán)。

控制臺(tái)中大量熱更新?

這可能是由循環(huán)依賴引起的。要解決這個(gè)問題，請(qǐng)先嘗試解決依賴循環(huán)。

構(gòu)建?

構(gòu)建產(chǎn)物因?yàn)?CORS 錯(cuò)誤無法工作?

如果導(dǎo)出的 HTML 文件是通過 file 協(xié)議打開的，那么其中的 script 將不會(huì)運(yùn)行，且報(bào)告下列錯(cuò)誤。

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).

請(qǐng)查看 釋因：CORS 請(qǐng)求不是 HTTP 請(qǐng)求 - HTTP | MDN 了解為什么會(huì)發(fā)生這種情況的更多信息。

你需要通過 http 協(xié)議訪問該文件。最簡單的辦法就是使用 npx vite preview。

其他?

Module externalized for browser compatibility?

當(dāng)你在瀏覽器中使用一個(gè) Node.js 模塊時(shí)，Vite 會(huì)輸出以下警告：

Module "fs" has been externalized for browser compatibility. Cannot access "fs.readFile" in client code.

這是因?yàn)?Vite 不會(huì)自動(dòng) polyfill Node.js 的內(nèi)建模塊。

我們推薦你不要在瀏覽器中使用 Node.js 模塊以減小包體積，盡管你可以為其手動(dòng)添加 polyfill。如果該模塊是被某個(gè)第三方庫（這里意為某個(gè)在瀏覽器中使用的庫）導(dǎo)入的，則建議向?qū)?yīng)庫提交一個(gè) issue。

出現(xiàn) Syntax Error 或 Type Error?

Vite 無法處理、也不支持僅可在非嚴(yán)格模式（sloppy mode）下運(yùn)行的代碼。這是因?yàn)?Vite 使用了 ESM 并且始終在 ESM 中使用 嚴(yán)格模式。

例如，你可能會(huì)看到以下錯(cuò)誤。

[ERROR] With statements cannot be used with the "esm" output format due to strict mode

TypeError: Cannot create property 'foo' on boolean 'false'

如果這些代碼是在依賴中被使用的，你應(yīng)該使用 patch-package（或者 yarn patch、pnpm patch 工具）來做短期補(bǔ)丁處理。