环境 API

候选发布版本 (Release Candidate)

环境 API 目前处于候选发布阶段。我们将在主要版本之间保持 API 的稳定性，以便生态系统能够进行实验和构建。但请注意，某些特定 API 仍被视为实验性的。

一旦下游项目有时间试验这些新功能并完成验证，我们计划在未来的主要版本中稳定这些新 API（可能会有破坏性变更）。

资源

反馈讨论区，我们在此处收集有关新 API 的反馈。
环境 API PR，新 API 在此进行实现和审查。

请与我们分享您的反馈。

环境的正式化

Vite 6 将“环境 (Environments)”的概念正式化。在 Vite 5 之前，存在两个隐式环境（client 和可选的 ssr）。新的环境 API 允许用户和框架作者创建任意数量的环境，以映射其应用在生产环境中的工作方式。这一新功能需要大规模的内部重构，但我们投入了大量精力来确保向后兼容性。Vite 6 的首要目标是尽可能顺利地将生态系统迁移到新版本，并延迟 API 的采用，直到足够的用户完成迁移，以及框架和插件作者验证了新设计。

缩小构建与开发之间的差距

对于简单的 SPA/MPA，配置中不会暴露任何关于环境的新 API。在内部，Vite 会将选项应用于 client 环境，但在配置 Vite 时无需了解这一概念。Vite 5 的配置和行为在此处应能无缝工作。

当我们转向典型的服务端渲染 (SSR) 应用时，我们将拥有两个环境：

client：在浏览器中运行应用。
ssr：在 Node（或其他服务器运行时）中运行应用，在发送给浏览器之前渲染页面。

在开发过程中，Vite 在与 Vite 开发服务器相同的 Node 进程中执行服务器代码，从而非常接近生产环境。然而，服务器也可以在其他 JS 运行时中运行，例如具有不同约束的 Cloudflare 的 workerd。现代应用可能还会运行在超过两个以上的环境中，例如浏览器、Node 服务器和边缘 (edge) 服务器。Vite 5 无法恰当地表示这些环境。

Vite 6 允许用户在构建和开发过程中配置其应用，以映射其所有环境。在开发阶段，现在可以使用单个 Vite 开发服务器同时在多个不同环境中运行代码。应用源码仍然由 Vite 开发服务器进行转换。在共享的 HTTP 服务器、中间件、已解析的配置和插件管道之上，Vite 开发服务器现在拥有了一组独立的环境。每个环境都配置为尽可能匹配生产环境，并连接到一个代码执行的开发运行时（例如，对于 workerd，服务器代码现在可以在本地运行在 miniflare 中）。在客户端，浏览器导入并执行代码。在其他环境中，模块运行器 (module runner) 会获取并评估转换后的代码。

Vite Environments

环境配置

对于 SPA/MPA，其配置将看起来与 Vite 5 相似。在内部，这些选项用于配置 client 环境。

export default defineConfig({
  build: {
    sourcemap: false,
  },
  optimizeDeps: {
    include: ['lib'],
  },
})

这一点很重要，因为我们希望保持 Vite 的易用性，并避免在需要之前暴露新的概念。

如果应用由多个环境组成，则可以使用 environments 配置选项显式配置这些环境。

export default {
  build: {
    sourcemap: false,
  },
  optimizeDeps: {
    include: ['lib'],
  },
  environments: {
    server: {},
    edge: {
      resolve: {
        noExternal: true,
      },
    },
  },
}

当未显式配置时，环境将继承配置的顶层选项（例如，新的 server 和 edge 环境将继承 build.sourcemap: false 选项）。少数几个顶层选项（如 optimizeDeps）仅适用于 client 环境，因为当它们作为服务器环境的默认选项时工作效果不佳。这些选项在参考文档中带有非继承徽章。client 环境也可以通过 environments.client 显式配置，但我们建议使用顶层选项进行配置，以便在添加新环境时保持客户端配置不变。

EnvironmentOptions 接口公开了所有针对环境的选项。有些环境选项同时适用于 build 和 dev，如 resolve。还有用于开发和构建特定选项的 DevEnvironmentOptions 和 BuildEnvironmentOptions（如 dev.warmup 或 build.outDir）。一些选项（如 optimizeDeps）仅适用于开发，但为了向后兼容，保留在顶层而不是嵌套在 dev 中。

interface EnvironmentOptions {
  define?: Record<string, any>
  resolve?: EnvironmentResolveOptions
  optimizeDeps: DepOptimizationOptions
  consumer?: 'client' | 'server'
  dev: DevOptions
  build: BuildOptions
}

UserConfig 接口继承自 EnvironmentOptions 接口，允许配置客户端以及其他通过 environments 选项配置的环境的默认值。在开发过程中，client 和名为 ssr 的服务器环境始终存在。这使得 server.ssrLoadModule(url) 和 server.moduleGraph 可以实现向后兼容。在构建过程中，client 环境始终存在，而 ssr 环境仅在显式配置时（使用 environments.ssr 或为了向后兼容使用 build.ssr）才会存在。应用无需使用 ssr 这个名称作为其 SSR 环境，例如，它可以将其命名为 server。

interface UserConfig extends EnvironmentOptions {
  environments: Record<string, EnvironmentOptions>
  // other options
}

请注意，一旦环境 API 稳定，ssr 顶层属性将被弃用。该选项的角色与 environments 相同，但仅针对默认的 ssr 环境，且仅允许配置少量选项。

自定义环境实例

底层配置 API 可供使用，以便运行时提供者能够为其运行时提供具有适当默认值的环境。这些环境也可以在开发过程中生成其他进程或线程，以在更接近生产环境的运行时中运行模块。

例如，Cloudflare Vite 插件使用环境 API 在开发期间在 Cloudflare Workers 运行时 (workerd) 中运行代码。

import { customEnvironment } from 'vite-environment-provider'

export default {
  build: {
    outDir: '/dist/client',
  },
  environments: {
    ssr: customEnvironment({
      build: {
        outDir: '/dist/ssr',
      },
    }),
  },
}

向后兼容性

当前的 Vite 服务器 API 尚未被弃用，并且与 Vite 5 向后兼容。

server.moduleGraph 返回客户端和 SSR 模块图的混合视图。其所有方法都将返回向后兼容的混合模块节点。传递给 handleHotUpdate 的模块节点也使用相同的方案。

我们目前不建议切换到环境 API。我们的目标是在更多用户群采用 Vite 6 之后，这样插件就不需要维护两个版本。请查看未来的破坏性变更部分，获取有关未来弃用和升级路径的信息。

目标用户

本指南为最终用户提供了关于环境的基本概念。

插件作者可以使用更一致的 API 来与当前环境配置进行交互。如果您是在 Vite 之上进行构建，环境 API 插件指南描述了支持多个自定义环境的扩展插件 API 使用方式。

框架可以决定在不同层级暴露环境。如果您是框架作者，请继续阅读环境 API 框架指南，了解环境 API 的编程层面。

对于运行时提供者，环境 API 运行时指南解释了如何提供自定义环境供框架和用户使用。

环境 API ​

环境的正式化 ​

缩小构建与开发之间的差距 ​

环境配置 ​

自定义环境实例 ​

向后兼容性 ​

目标用户 ​