问题排查

另请参阅 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 中，默认情况下不能通过 require 加载 ESM 文件。

虽然使用 --experimental-require-module，或者 Node.js >22，或者在其他运行时中可能会起作用，但我们仍然建议通过以下方式将您的配置转换为 ESM

• 将 "type": "module" 添加到最近的 package.json
• 将 vite.config.js/vite.config.ts 重命名为 vite.config.mjs/vite.config.mts

开发服务器

请求永远停滞

如果您使用的是 Linux，文件描述符限制和 inotify 限制可能会导致此问题。由于 Vite 不会捆绑大多数文件，浏览器可能会请求许多文件，这需要许多文件描述符，从而超出限制。

要解决此问题

• 通过 ulimit 增加文件描述符限制

  # 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 相关限制

  # 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 中运行，则请求可能看起来已停滞。要解决此问题，请参阅 Dev Containers / VS Code 端口转发。

网络请求停止加载

当使用自签名 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 标头时，请求将被丢弃，并将显示以下警告。

Server responded with status code 431. See https://vite.vuejs.ac.cn/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 包含

import './Foo.js' // should be './foo.js'

相关问题：#964

Vite 未检测到文件更改

如果您使用 WSL2 运行 Vite，在某些情况下，Vite 无法监视文件更改。请参阅 server.watch 选项。

发生完全重新加载而不是 HMR

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

如果 HMR 已处理，但它在循环依赖中，则也会发生完全重新加载以恢复执行顺序。要解决此问题，请尝试打破循环。如果文件更改触发了循环依赖，您可以运行 vite --debug hmr 来记录循环依赖路径。

构建

由于 CORS 错误，构建的文件无法正常工作

如果 HTML 文件输出是用 file 协议打开的，则脚本将无法运行，并出现以下错误。

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。

优化的依赖项

链接到本地包时，预捆绑的依赖项已过时

用于使优化的依赖项无效的哈希键取决于包锁内容、应用于依赖项的补丁以及影响节点模块捆绑的 Vite 配置文件中的选项。这意味着 Vite 将检测到何时使用诸如 npm overrides 之类的功能覆盖依赖项，并在下次服务器启动时重新捆绑您的依赖项。当您使用诸如 npm link 之类的功能时，Vite 不会使依赖项无效。如果您链接或取消链接依赖项，则需要在下次服务器启动时使用 vite --force 强制重新优化。我们建议改用 overrides，现在每个包管理器都支持它（另请参阅 pnpm overrides 和 yarn resolutions）。

性能瓶颈

如果您的应用程序遇到任何导致加载时间缓慢的性能瓶颈，您可以使用内置的 Node.js 检查器启动 Vite 开发服务器或构建应用程序，以创建 CPU 配置文件

开发服务器

vite --profile --open

构建

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 模块。

我们建议避免将 Node.js 模块用于浏览器代码，以减小捆绑包大小，尽管您可以手动添加 polyfills。如果该模块是从第三方库导入的（用于在浏览器中使用），则建议向相应的库报告该问题。

发生语法错误/类型错误

Vite 无法处理且不支持仅在非严格模式（宽松模式）下运行的代码。这是因为 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 开发服务器。在这种情况下，您可能会看到一个空白屏幕，没有记录错误。如果遇到此问题，请尝试禁用扩展。

Windows 上的跨驱动器链接

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

跨驱动器链接的示例包括

• 通过 subst 命令链接到文件夹的虚拟驱动器
• 通过 mklink 命令链接到不同驱动器的符号链接/联结（例如 Yarn 全局缓存）

相关问题：#10802