故障排查与常见问题

vite-main常见问题与故障排查

故障排查与常见问题

更多信息请参阅 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 复制代码

# 检查当前限制
$ ulimit -Sn
# 修改限制（临时）
$ ulimit -Sn 10000 # 你可能也需要修改硬限制
# 重启你的浏览器

通过 sysctl 提高以下与 inotify 相关的限制

shell 复制代码

# 检查当前限制
$ 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，你可能需要在文件 /etc/security/limits.conf 中添加一行 * - nofile 65536，而不是更新 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 复制代码

# 检查当前限制
$ cat /proc/sys/fs/inotify/max_user_watches
# 提高限制（临时）
$ sudo sysctl fs.inotify.max_user_watches=524288
# 永久生效 - 添加到 /etc/sysctl.conf（如果已存在则编辑）
$ 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 issue

macOS

你可以通过命令行安装受信任的证书：

复制代码

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

或者，将其导入到“钥匙串访问”（Keychain Access）应用中，并将证书的信任设置为“始终信任”。

当服务器 / WebSocket 服务器收到过大的 HTTP 头时，请求将被丢弃，并显示以下警告。

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

这是因为 Node.js 限制了请求头的大小以缓解 CVE-2018-12121 漏洞。

为避免此问题，请尝试减小请求头大小。例如，如果 cookie 太长，请删除它。或者，你可以使用 --max-http-header-size 来更改最大头大小。

Dev Containers / VS Code 端口转发

如果你在 VS Code 中使用 Dev Container 或端口转发功能，你可能需要在配置中设置 server.host 选项为 127.0.0.1。

这是因为 VS Code 的端口转发功能不支持 IPv6。

更多详情请参见 #16522。

HMR

Vite 检测到文件变更但 HMR 不工作

你可能正在以不同的大小写导入文件。例如，src/foo.js 存在，而 src/bar.js 包含：

js 复制代码

import './Foo.js' // 应该是 './foo.js'

Vite 没有检测到文件变更

如果你在 WSL2 中运行 Vite，在某些情况下 Vite 可能无法监视文件变化。请参阅 server.watch 选项。

发生整页重新加载而不是 HMR

如果 HMR 未由 Vite 或插件处理，则会发生整页重新加载，因为这是刷新状态的唯一方法。

如果 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。

由于大小写敏感导致的 No such file or directory 错误

如果你遇到类似 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 文件仍引用已在新部署中被删除的旧 chunk 名称。这发生在以下情况：

用户浏览器缓存了旧版本的应用
你部署了新版本，但 chunk 名称因代码更改而不同
缓存的 HTML 试图加载不再存在的 chunk

如果你使用的是框架，请首先参阅其文档，因为框架可能有内置的解决方案。

你可以通过以下方式解决：

暂时保留旧 chunk：考虑将先前部署的 chunk 保留一段时间，以便缓存的用户平滑过渡。
使用 Service Worker：实现一个 Service Worker，预取并缓存所有资源。
预取动态 chunk：请注意，如果你的 HTML 文件因 Cache-Control 头被浏览器缓存，则此方法无效。
实现优雅的降级方案：为动态导入实现错误处理，以便在 chunk 丢失时重新加载页面。更多详情请参阅加载错误处理。

网络状况不佳

此错误可能在不稳定的网络环境中发生。例如，当请求因网络错误或服务器宕机而失败时。

请注意，由于浏览器限制，你无法重试动态导入（whatwg/html#6768）。

浏览器扩展阻止请求

如果浏览器扩展（如广告拦截器）阻止了该请求，也可能发生此错误。

可以通过 build.rolldownOptions.output.chunkFileNames 选择不同的 chunk 名称来解决，因为这些扩展通常根据文件名（例如，包含 ad、track 的名称）阻止请求。

优化依赖

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

用于使优化依赖失效的哈希键取决于包锁文件内容、应用于依赖的补丁以及 Vite 配置文件中影响 node 模块打包的选项。这意味着 Vite 会检测到使用如 npm overrides 等功能覆盖的依赖，并在下次服务器启动时重新打包这些依赖。但当你使用像 npm link 这样的功能时，Vite 不会使依赖失效。如果你链接或取消链接了某个依赖，则需要在下次服务器启动时使用 vite --force 强制重新优化。我们建议改用 overrides，现在所有包管理器都支持该功能（另请参阅 pnpm overrides 和 yarn resolutions）。

性能瓶颈

如果你的应用出现任何性能瓶颈导致加载时间变慢，你可以在 Vite 开发服务器或构建应用时启动内置的 Node.js 检查器来生成 CPU 性能分析文件：

code-group
bash [开发服务器] 复制代码
vite --profile --open
bash [构建] 复制代码
vite build --profile

::: tip 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。如果该模块是从第三方库导入的（并且该库设计用于浏览器），建议向该库报告此问题。

发生 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）作为临时解决方案。

浏览器扩展

某些浏览器扩展（如广告拦截器）可能会阻止 Vite 客户端向 Vite 开发服务器发送请求。在这种情况下，你可能会看到白屏且没有错误日志。你也可能会看到以下错误：

TypeError: Failed to fetch dynamically imported module

如果遇到此问题，请尝试禁用扩展。

Windows 上的跨驱动器链接

如果你的项目在 Windows 上存在跨驱动器链接，Vite 可能无法正常工作。

跨驱动器链接的示例包括：

通过 subst 命令链接到文件夹的虚拟驱动器
通过 mklink 命令创建的指向其他驱动器的符号链接/联接（例如，Yarn 全局缓存）

默认导入意外返回一个对象

对于 CJS 模块，默认导入返回的是 module.exports 对象，而你可能期望它返回 module.exports.default 的值。

这可能会导致如下错误：

Element type is invalid: expected a string (for built-in components) or a class/function (for composite components) but got: object.

foo is not a function

有关此问题的更多详情，请参阅 Rolldown 的文档：来自 CJS 模块的歧义 default 导入 - 打包 CJS | Rolldown。

帮助我们改进文档

发现翻译问题或内容错误？请告诉我们。

故障排查与常见问题

故障排查与常见问题

CLI

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

配置

该包仅为 ESM

开发服务器

请求无限挂起

Vite 因 ENOSPC 错误崩溃

网络请求停止加载

macOS

431 Request Header Fields Too Large

Dev Containers / VS Code 端口转发

HMR

Vite 检测到文件变更但 HMR 不工作

Vite 没有检测到文件变更

发生整页重新加载而不是 HMR

构建

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

由于大小写敏感导致的 No such file or directory 错误

Failed to fetch dynamically imported module 错误

版本偏差

网络状况不佳

浏览器扩展阻止请求

优化依赖

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

性能瓶颈

其他

模块为浏览器兼容性而外置

发生 Syntax Error / Type Error

浏览器扩展

Windows 上的跨驱动器链接

默认导入意外返回一个对象

帮助我们改进文档

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

`Failed to fetch dynamically imported module` 错误