Vite

英语

简体中文
日本語
西班牙语
葡萄牙语
한국어
德语

英语

简体中文
日本語
西班牙语
葡萄牙语
한국어
德语

外观

超越速度

ViteConf 2023

观看回放！

疑难解答 ​

有关更多信息，请参阅 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 (.mts 或 .ts 在 "type": "module" 中)。如果您有使用 .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 加载。

"foo" 解析为 ESM 文件。ESM 文件无法通过 require 加载。

ESM 文件无法通过 require 加载。

我们建议通过以下任一方式将您的配置转换为 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 错误而无法工作 ​

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

优化依赖项 ​

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

用于使优化依赖项失效的哈希键取决于包锁定内容、应用于依赖项的补丁以及影响节点模块捆绑的 Vite 配置文件中的选项。这意味着 Vite 将检测到何时使用诸如 npm overrides 之类的功能覆盖依赖项，并在下次服务器启动时重新捆绑您的依赖项。当您使用诸如 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 将输出以下警告。

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

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

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

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

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 项目中存在跨驱动器链接，Vite 可能无法正常工作。

跨驱动器链接的示例包括

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

相关问题：#10802