# 故障排除

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

如果这里的建议并未帮助到你，请将你的问题发送到 GitHub 讨论区 或 Vite Land Discord 的 #help频道。

# CLI

# `Error: Cannot find module 'C:\foo\bar&baz\vite\bin\vite.js'`¶ (opens new window)

你的项目文件夹路径中可能包含了符号 &，这在 Windows 上无法与 npm配合正常工作 (npm/cmd-shim#45 (opens new window) )。

你可以选择以下两种修改方式：

切换另一种包管理工具（例如 pnpm或 yarn）
从你的项目路径中移除符号 &

# 开发服务器

# 请求始终停滞

如果你使用的是 Linux，文件描述符限制和 inotify 限制可能会导致这个问题。由于 Vite 不会打包大多数文件，浏览器可能会请求许多文件，而相应地需要许多文件描述符，因此超过了限制。

要解决这个问题：

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

# 查看当前限制值
$ ulimit -Sn
# （暂时）更改限制值
$ ulimit -Sn 10000 # 你可能也需要更改硬性限制值
# 重启你的浏览器

通过 sysctl提升下列 inotify 相关的限制

# 查看当前限制值
$ sysctl fs.inotify
# （暂时）更改限制值
$ 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 配置文件。

请注意，这些配置会持久作用，但需要 重新启动。

# 网络请求停止加载

使用自签名SSL证书时，Chrome 会忽略所有缓存指令并重新加载内容。而 Vite 依赖于这些缓存指令。

要解决此问题，请使用受信任的SSL证书。

请查看：缓存问题 (opens new window) 和相关的 Chrome issue

# macOS

您可以使用以下命令通过 CLI 安装受信任的证书：

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

或者，通过将其导入 Keychain Access 应用程序并将您的证书的信任更新为“始终信任”。

# 431 Request Header Fields Too Large

当服务器或 WebSocket 服务收到一个较大的 HTTP 头，该请求可能会被遗落并且会显示下面这样的警告。

Server responded with status code 431. See https://vitejs.dev/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' // 应该为 './foo.js'

# Vite 没有检测到文件变化

如果你正在 WSL2 中运行 Vite，Vite 无法在某些场景下监听文件变化。请查看 server.watch 选项 的描述。

# 完全重新加载了，而不是 HMR

如果 HMR 不是由 Vite 或一个插件处理的，那么将进行完全的重新加载。

同时如果有依赖环，也会发生完全重载。要解决这个问题，请先尝试解决依赖循环。

# 控制台中大量热更新

This can be caused by a circular dependency. To solve this, try breaking the loop.

# 构建

# 构建产物因为 CORS 错误无法工作

如果导出的 HTML 文件是通过 file协议打开的，那么其中的 script 将不会运行，且报告下列错误。

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

请查看 释因：CORS 请求不是 HTTP 请求 - HTTP | MDN 了解为什么会发生这种情况的更多信息。

你需要通过 http协议访问该文件。最简单的办法就是使用 npx vite preview。

# 其他

# Module externalized for browser compatibility

当你在浏览器中使用一个 Node.js 模块时，Vite 会输出以下警告：

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

这是因为 Vite 不会自动 polyfill Node.js 的内建模块。

我们推荐你不要再浏览器中使用 Node.js 模块以减小包体积，尽管你可以为其手动添加 polyfill。如果该模块是被某个第三方库（这里意为某个在浏览器中使用的库）导入的，则建议向对应库提交一个 issue。

# Syntax Error / Type Error

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 (opens new window) 工具）来做短期补丁处理。

← 与其他工具比较从 v3 迁移 →