环境 API

实验性

环境 API 处于实验阶段。在 Vite 6 期间，我们将保持 API 稳定，以使生态系统能够进行实验并在其基础上构建。我们计划在 Vite 7 中稳定这些新的 API，可能会进行重大更改。

资源

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

请与我们分享您的反馈。

规范化环境

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

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

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

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

client：在浏览器中运行应用程序。
server：在 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 环境，因为将它们作为服务器环境的默认值应用效果不佳。也可以通过 environments.client 显式配置 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 环境始终存在，并且只有在显式配置时（使用 environments.ssr 或为了向后兼容性而使用 build.ssr）才会存在 ssr 环境。应用程序不需要为其 SSR 环境使用 ssr 名称，例如，它可以将其命名为 server。

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

请注意，一旦环境 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 向后兼容。新的环境 API 处于实验阶段。

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

我们不建议立即切换到环境 API。我们的目标是让很大一部分用户群采用 Vite 6，这样插件就不需要维护两个版本。查看未来的重大更改部分以获取有关未来弃用和升级路径的信息

目标用户

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

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

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

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

环境 API ​

规范化环境 ​

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

环境配置 ​

自定义环境实例 ​

向后兼容性 ​

目标用户 ​