vite

Vite

快速导航

• 开始使用：references/getting-started.md
• 理念与原理：references/philosophy.md, references/why-vite.md
• 功能：references/features.md
• CLI：references/cli.md
• 插件（用法）：references/using-plugins.md
• 插件 API：references/api-plugin.md
• HMR API：references/api-hmr.md
• JavaScript API：references/api-javascript.md
• 配置参考：references/config.md
• 依赖优化：references/dep-pre-bundling.md
• 资源：references/assets.md
• 构建：references/build.md
• 静态部署：references/static-deploy.md
• 环境变量与模式：references/env-and-mode.md
• SSR：references/ssr.md
• 后端集成：references/backend-integration.md
• 故障排除：references/troubleshooting.md
• 性能：references/performance.md
• Rolldown：references/rolldown.md
• 迁移：references/migration.md
• 破坏性变更：references/breaking-changes.md
• 环境 API：references/api-environment.md
• 环境实例：references/api-environment-instances.md
• 环境插件：references/api-environment-plugins.md
• 环境框架：references/api-environment-frameworks.md
• 环境运行时：references/api-environment-runtimes.md

核心规则

• 优先采用最少配置；仅在需要时扩展。
• 使用 Vite 默认设置时，将 index.html 作为一等入口。
• 分别处理开发服务设置和构建设置。
• 说明环境变量和 define 随模式变化的行为。
• 使用 future 配置，在迁移前启用弃用警告。

实用方案

• 使用 npm create vite@latest 搭建项目。
• 在 vite.config.* 中配置别名、服务选项和构建输出。
• 当配置需要 .env 值时，使用 loadEnv 将其加载到配置中。
• 使用 plugins: [] 添加插件，并在需要时定义 apply 或 enforce。
• 当插件或框架需要时，使用 HMR API 实现细粒度更新。
• 当依赖未在启动时被发现时，使用 optimizeDeps.include/exclude。
• 对于多页面应用，使用 build.rollupOptions.input。
• 对于没有 index.html 的应用，使用顶层 input 选项声明一次入口；默认情况下，它会传递给 build.rolldownOptions.input、build.lib.entry、build.ssr 和 optimizeDeps.entries。
• 启用弃用警告：future: { removeSsrLoadModule: 'warn' }。
• 使用 hotUpdate 钩子代替 handleHotUpdate，以支持感知环境的 HMR。
• 在插件钩子中使用 this.environment 代替 options.ssr。

版本亮点（8.0.0）

• 在 baseline-widely-available 下再次提高默认浏览器目标版本。
• CommonJS 默认导入互操作行为更加一致，并可能暴露依赖旧版模糊行为的包。
• Vite 不再通过格式检测来解析 browser 与 module，而是更严格地遵循配置的 resolve.mainFields。
• 当存在多个 Rolldown 层级的错误时，JavaScript API build() 现在会抛出包含嵌套 .errors 的 BundleError。
• Rolldown 迁移更加明确：build.rollupOptions / worker.rollupOptions 已弃用，改用 *.rolldownOptions。

版本亮点（8.1.0 -> 8.1.5）

• WASM ESM 集成：原生支持将 .wasm 直接导入为 ES 模块。
• 零配置构建缓存：集成 Vite Task，无需手动设置即可启用构建缓存。
• server.hmr 更名为 server.ws：WebSocket 选项移至 server.ws 下；请更新设置了 HMR 传输选项的配置。
• 新增选项：用于 HTML 转换期间自定义资源来源的 html.additionalAssetSources、import.meta.glob 的 caseSensitive、通过 __VITE_ADDITIONAL_SERVER_ALLOWED_HOSTS 支持多个主机，以及扩展后的默认 server.fs.deny 列表。
• 8.1.1 -> 8.1.5：仅包含稳定性改进（堆栈跟踪处理、依赖升级、模块解析边缘情况）。

版本亮点（8.2.0）

• 新增顶层 input 选项：input: string | string[] | { [entryAlias: string]: string } 会相对于项目根目录解析，并在以下选项未设置时，作为 build.rolldownOptions.input、build.lib.entry、build.ssr（设为 true 时）和 optimizeDeps.entries 的默认值；适用于跳过 index.html 的应用，这类应用原本需要在多个选项中重复填写相同的入口路径。解析后的 input 路径也会添加到 server.fs.allow，与已导入模块的处理方式一致。
• 打包式开发模式（experimental.bundledDev）：无边界编辑现在只会触发一次重新加载；客户端会先通知服务端进行重新构建，然后才发送 full-reload，因此编辑后重新加载前不再闪现“正在打包”回退页面。Worker 文件（new Worker(new URL(...))、?worker 导入）现在也会通过 HMR 正确重新生成，不会在编辑后变为过时文件。
• 原生加载器／原生配置兼容性：关于 configLoader: 'native' 不支持的功能的警告现在会在行号旁显示列号；虚拟模块也会从原生配置兼容性检查中排除，因此插件生成的虚拟文件不再触发误报。
• 类型安全的 PostCSS 配置：Vite 导出 PostcssUserConfig（重新导出自 postcss-load-config 的 Config 类型），因此可以直接为 postcss.config.js／.ts 添加类型。
• 网络 URL 标注：开发服务器现在会解析并打印操作系统网络接口名称（例如 eth0、wlan0），即使 server.host 是显式地址也不例外，不再仅在 Vite 自动检测所有接口时才显示。
• Rolldown 和依赖优化器更新：Rolldown 升级至 ~1.2.0，客户端 HMR 处理也因此纳入 experimental.bundledDev；依赖优化器的锁文件哈希缓存现在还会识别 aube-lock.yaml（Aube）和 nub.lock（nub），因此这些包管理器会在依赖变更时正确地使 node_modules/.vite 缓存失效。

补丁说明（8.0.14 -> 8.0.16）

• Rolldown 升级至 1.0.3（8.0.14 中为 1.0.2）；如果你负责维护插件或构建指南，请根据当前 Rolldown 行为进行验证，而不要假设早期 8.0.x 补丁版本的行为仍然适用。
• 开发服务器现在会在请求超时时发送 HTTP 408，不再挂起连接（8.0.15）。
• launch-editor-middleware 会拒绝 UNC 路径和 Windows 备用路径，修复本地路径遍历漏洞（8.0.16）；如果你将开发服务器暴露给 localhost 以外的网络，此修复与你相关。
• 8.0.15 修复了以下问题：/@fs/ HTML 代理缓存键不匹配、虚拟模块中无匹配文件时相对 glob 报错、write() 被拒绝时关闭 Rolldown 包，以及 JS 插件容器中 viteResolvePlugin 的 onWarn。
• transformIndexHtml 对尾部斜杠路径的处理更加可靠，这对会重写或注入目录形式 URL 对应 HTML 的插件和静态部署配置尤为重要。
• 依赖扫描现在会在优化器流程中传递 Oxc JSX 选项，因此包含大量 JSX 的链接依赖，其行为应更接近主转换流程。

禁止事项

• 不要大段照搬供应商文档中的原文。
• 未经验证，不要假设某个框架特有的行为。

链接

• 文档
• 发布记录
• GitHub
• npm