故障排除

另请参阅 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 增加文件描述符限制

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，你可能需要将 * - 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 个。

要解决此问题，你可以：

增加系统文件监视器限制

shell

# 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.org.cn/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'

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 名称。这种情况发生在：

用户在浏览器中缓存了旧版本的应用程序
你部署了具有不同 chunk 名称的新版本（由于代码更改）
缓存的 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 性能分析文件：

开发服务器构建

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 会输出以下警告：

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 全局缓存）

故障排除 ​

CLI ​

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

配置 ​

此包仅限 ESM ​

开发服务器 ​

请求无限期挂起 ​

Vite 因 ENOSPC 错误而崩溃 ​

网络请求停止加载 ​

macOS ​

431 Request Header Fields Too Large ​

开发容器 / VS Code 端口转发 ​

HMR (模块热替换) ​

Vite 检测到文件更改，但 HMR 不起作用 ​

Vite 未检测到文件更改 ​

发生了全量重新加载而不是 HMR ​

构建 ​

构建出的文件因 CORS 错误无法工作 ​

由于大小写敏感导致“找不到文件或目录”错误 ​

Failed to fetch dynamically imported module 错误 ​

版本偏差 ​

网络状况不佳 ​

浏览器扩展拦截请求 ​

依赖项优化 ​

链接本地包时预构建依赖项过时 ​

性能瓶颈 ​

其他 ​

为浏览器兼容性外部化模块 ​

出现语法错误 / 类型错误 ​

浏览器扩展 ​

Windows 上的跨驱动器链接 ​

故障排除

CLI

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

配置

此包仅限 ESM

开发服务器

请求无限期挂起

Vite 因 ENOSPC 错误而崩溃

网络请求停止加载

macOS

431 Request Header Fields Too Large

开发容器 / VS Code 端口转发

HMR (模块热替换)

Vite 检测到文件更改，但 HMR 不起作用

Vite 未检测到文件更改

发生了全量重新加载而不是 HMR

构建

构建出的文件因 CORS 错误无法工作

由于大小写敏感导致“找不到文件或目录”错误

`Failed to fetch dynamically imported module` 错误

版本偏差

网络状况不佳

浏览器扩展拦截请求

依赖项优化

链接本地包时预构建依赖项过时

性能瓶颈

其他

为浏览器兼容性外部化模块

出现语法错误 / 类型错误

浏览器扩展

Windows 上的跨驱动器链接