Environment API

实验性功能

Environment API 是一项实验性功能。我们仍将在主要版本之间保持 API 的稳定性，以允许生态系统进行实验和构建。我们计划在未来的主要版本中稳定这些新 API（可能包含破坏性更改），以便下游项目有时间试验新功能并验证它们。

资源

反馈讨论，我们正在其中收集有关新 API 的反馈。
Environment API PR，其中实现了新的 API 并进行了审查。

请与我们分享您的反馈。

正式化环境

Vite 6 正式化了环境的概念。在 Vite 5 之前，存在两个隐式环境（client 和可选的 ssr）。新的 Environment API 允许用户和框架作者创建所需的任意数量的环境，以映射其应用程序在生产环境中的工作方式。这项新功能需要进行大量的内部重构，但我们已尽力确保向后兼容性。Vite 6 的最初目标是使生态系统尽可能顺利地迁移到新版本，将这些新的实验性 API 的采用推迟到有足够多的用户迁移并且框架和插件作者已经验证了新设计之后。

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

对于简单的 SPA/MPA，没有关于环境的新 API 公开给配置。在内部，Vite 会将选项应用于 client 环境，但在配置 Vite 时无需了解此概念。Vite 5 的配置和行为应在此处无缝运行。

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

client：在浏览器中运行应用程序。
ssr：在 node（或其他服务器运行时）中运行应用程序，在将页面发送到浏览器之前呈现页面。

在开发中，Vite 在与 Vite 开发服务器相同的 Node 进程中执行服务器代码，从而可以很好地近似生产环境。但是，服务器也可以在其他 JS 运行时中运行，例如 Cloudflare 的 workerd，这些运行时具有不同的约束。现代应用程序也可能在两个以上的环境中运行，例如浏览器、node 服务器和边缘服务器。Vite 5 不允许正确表示这些环境。

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

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
}

请注意，一旦 Environment API 稳定，ssr 顶级属性将被弃用。此选项与 environments 的作用相同，但对于默认的 ssr 环境，并且仅允许配置一小部分选项。

自定义环境实例

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

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

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

向后兼容性

当前的 Vite 服务器 API 尚未弃用，并且与 Vite 5 向后兼容。新的 Environment API 是一项实验性功能。

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

我们不建议立即切换到 Environment API。我们的目标是在插件不需要维护两个版本之前，让很大一部分用户群采用 Vite 6。请查看未来的破坏性更改部分，了解有关未来弃用和升级路径的信息

目标用户

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

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

框架可能会决定在不同的级别公开环境。如果您是框架作者，请继续阅读 Environment API 框架指南，以了解 Environment API 的编程方面。

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

Environment API ​

正式化环境 ​

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

环境配置 ​

自定义环境实例 ​

向后兼容性 ​

目标用户 ​