Vite

English

简体中文
日本語
Español
Português
한국어
Deutsch

English

简体中文
日本語
Español
Português
한국어
Deutsch

外观

ViteConf Logo

携手共建

ViteConf 2024

观看回放！

疑难解答 ​

另请参阅 Rollup 的疑难解答指南 以获取更多信息。

如果此处提供的建议不起作用，请尝试在 GitHub 讨论区 或 Vite Land Discord 的 #help 频道中发布问题。

CJS ​

Vite CJS Node API 已弃用 ​

Vite 的 Node API 的 CJS 版本已弃用，将在 Vite 6 中移除。请参阅 GitHub 讨论 以获取更多上下文。您应该更新您的文件或框架以改为导入 Vite 的 ESM 版本。

在基本的 Vite 项目中，请确保

  1. vite.config.js 文件内容使用 ESM 语法。
  2. 最接近的 package.json 文件具有 "type": "module"，或者使用 .mjs/.mts 扩展名，例如 vite.config.mjs 或 vite.config.mts。

对于其他项目，有几种通用的方法

  • 将 ESM 设为默认，并在需要时选择使用 CJS：在项目 package.json 中添加 "type": "module"。现在所有 *.js 文件都被解释为 ESM，并且需要使用 ESM 语法。您可以将文件重命名为 .cjs 扩展名以继续使用 CJS。
  • 将 CJS 设为默认，并在需要时选择使用 ESM：如果项目 package.json 中没有 "type": "module"，则所有 *.js 文件都被解释为 CJS。您可以将文件重命名为 .mjs 扩展名以改为使用 ESM。
  • 动态导入 Vite：如果您需要继续使用 CJS，则可以使用 import('vite') 动态导入 Vite。这要求您的代码在 async 上下文中编写，但由于 Vite 的 API 大部分是异步的，因此仍然可以管理。

如果您不确定警告来自哪里，可以使用 VITE_CJS_TRACE=true 标志运行脚本以记录堆栈跟踪

bash
VITE_CJS_TRACE=true vite dev

如果您想暂时忽略警告，可以使用 VITE_CJS_IGNORE_WARNING=true 标志运行脚本

bash
VITE_CJS_IGNORE_WARNING=true vite dev

请注意，postcss 配置文件尚不支持 ESM + TypeScript（在 "type": "module" 中使用 .mts 或 .ts）。如果您有使用 .ts 的 postcss 配置并向 package.json 中添加了 "type": "module"，则还需要将 postcss 配置重命名为使用 .cts。

CLI ​

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

您的项目文件夹路径可能包含 &，这在 Windows 上与 npm 不兼容（npm/cmd-shim#45）。

您需要：

  • 切换到其他包管理器（例如 pnpm、yarn）
  • 从项目路径中删除 &

配置 ​

此包仅限 ESM ​

当通过 require 导入仅限 ESM 的包时，会发生以下错误。

无法解析 "foo"。此包仅限 ESM，但尝试通过 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 配置文件。

请注意，这些设置会持久存在，但**需要重新启动**。

网络请求停止加载 ​

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

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

请参阅：缓存问题、Chrome 问题

macOS ​

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

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

或者，将其导入到钥匙串访问应用程序中，并将证书的信任更新为“始终信任”。

431 请求标头字段过多 ​

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

服务器返回状态代码 431。请参阅 https://vite.vuejs.ac.cn/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 包含

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 配置文件中的选项。这意味着当使用诸如 npm overrides 的功能覆盖依赖项时，Vite 会检测到并重新捆绑您的依赖项在下一次服务器启动时。当您使用诸如 npm link 的功能时，Vite 不会使依赖项失效。如果您链接或取消链接依赖项，则需要在下一次服务器启动时使用 vite --force 强制重新优化。我们建议改用覆盖，现在每个包管理器都支持覆盖（另请参阅 pnpm overrides 和 yarn resolutions）。

性能瓶颈 ​

如果您遇到任何导致加载时间缓慢的应用程序性能瓶颈，您可以使用内置的 Node.js 检查器启动您的 Vite 开发服务器或在构建应用程序时创建 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 插件的中间状态，还可以帮助您识别应用程序中的哪些插件或中间件是瓶颈。该插件可以在开发和构建模式下使用。查看自述文件以了解更多详细信息。

其他 ​

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

当您在浏览器中使用 Node.js 模块时，Vite 将输出以下警告。

模块“fs”已为浏览器兼容性外部化。无法在客户端代码中访问“fs.readFile”。

这是因为 Vite 不会自动填充 Node.js 模块。

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

发生语法错误/类型错误 ​

Vite 无法处理也不支持仅在非严格模式（松散模式）下运行的代码。这是因为 Vite 使用 ESM，并且在 ESM 内部始终处于 严格模式。

例如，您可能会看到以下错误。

[错误] 由于严格模式，with 语句不能与“esm”输出格式一起使用

TypeError: 无法在布尔值“false”上创建属性“foo”

如果这些代码在依赖项内部使用，您可以使用 patch-package（或 yarn patch 或 pnpm patch）作为一种应急方案。

浏览器扩展 ​

某些浏览器扩展（如广告拦截器）可能会阻止 Vite 客户端向 Vite 开发服务器发送请求。在这种情况下，您可能会看到一个没有记录错误的白屏。如果您遇到此问题，请尝试禁用扩展。

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

跨驱动器链接的示例是

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

相关问题： #10802

在 MIT 许可证下发布。（ccee3d7c）

版权所有 © 2019-至今 VoidZero Inc. 及 Vite 贡献者