Environment API 概述

vite-mainAPI 参考

Environment API 概述

:::info 发布候选版本
Environment API 总体上已进入发布候选阶段。我们将在主要版本之间保持 API 的稳定性，以便生态系统能够进行实验并在此基础上构建。但请注意，某些特定 API 仍被视为实验性功能。

我们计划在未来的主要版本中稳定这些新 API（可能包含破坏性变更），前提是下游项目已有足够时间体验新功能并对其进行验证。

资源：

反馈讨论我们正在这里收集关于新 API 的反馈。
Environment API PR 新 API 在此实现并进行了审查。

欢迎与我们分享您的反馈。
:::

形式化环境

Vite 6 形式化了“环境”（Environment）的概念。在 Vite 5 之前，只有两个隐式环境（client 和可选的 ssr）。新的 Environment API 允许用户和框架作者根据其应用在生产环境中的运行方式，创建所需数量的环境。这一新能力需要进行大规模的内部重构，但我们在向后兼容性方面投入了大量精力。Vite 6 的初始目标是让生态系统尽可能平滑地迁移到新的大版本，推迟 API 的采用，直到有足够多的用户完成迁移，并且框架和插件作者验证了新设计。

弥合构建与开发之间的差距

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

当我们转向典型的服务端渲染（SSR）应用时，会有两个环境：

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

在开发环境中，Vite 在与 Vite 开发服务器相同的 Node.js 进程中执行服务端代码，从而与生产环境高度接近。然而，服务器也有可能运行在其他 JS 运行时中，例如 Cloudflare 的 workerd，它们具有不同的约束条件。现代应用也可能运行在不止两个环境中，例如浏览器、Node.js 服务器和边缘服务器。Vite 5 无法很好地表示这些环境。

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

环境配置

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

js 复制代码

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

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

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

js 复制代码

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 下。

ts 复制代码

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。

ts 复制代码

interface UserConfig extends EnvironmentOptions {
  environments: Record<string, EnvironmentOptions>
  // 其他选项
}

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

自定义环境实例

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

例如，Cloudflare Vite 插件使用 Environment API 在开发期间于 Cloudflare Workers 运行时（workerd）中运行代码。

js 复制代码

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 的模块节点也采用相同的方案。

我们目前不建议切换到 Environment API。我们希望在插件无需维护两个版本的情况下，让相当一部分用户群采用 Vite 6。请查看未来的破坏性变更部分，了解未来的弃用和迁移路径信息：

目标用户

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

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

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

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

帮助我们改进文档

发现翻译问题或内容错误？请告诉我们。