Vite 环境 API 如何为多运行时组织构建配置

当一个项目同时要跑浏览器、Node 服务端和 Edge Worker 时，真正难的不是再写一份 vite.config，而是把“运行时差异”放在正确的边界里。Vite Environment API 的做法是：用命名 environment 描述生产运行时，顶层配置承载公共规则，再用 environments 为服务端或 Edge 做局部覆盖。

官方地址：https://vite.dev/guide/api-environment

先按生产形态划分环境，再映射到 Vite

先列部署结果，再决定 environment 名称。浏览器代码需要 DOM 和 Web API，可以对应 client；Node SSR 需要文件系统或 Node 内置模块，可以对应 server；Cloudflare Workers 一类运行时则可以对应 edge。名称不必拘泥于 ssr，关键是它能准确表达运行时约束。

开发时，一个 Vite dev server 可以承载多个相互独立的开发环境：源文件仍由同一套转换和插件管线处理，模块则交给各环境的运行时执行。这样，服务端代码不必伪装成浏览器代码，Edge 代码也不会被 Node 的假设污染。

公共配置要复用，运行时差异要显式覆盖

最小配置可以把源码映射策略放在顶层，把输出目录和依赖解析放到具体环境。下面的写法表达的是配置关系；具体框架仍要确认它是否已经消费这些 environment。

import { defineConfig } from 'vite'

export default defineConfig({
  // 所有环境默认共享这条构建规则
  build: {
    sourcemap: true,
  },
  environments: {
    server: {
      // 服务端产物单独输出，避免和浏览器资源混在一起
      build: {
        outDir: 'dist/server',
      },
    },
    edge: {
      // Edge 运行时通常需要把依赖一起处理，减少 Node 专属外部依赖
      resolve: {
        noExternal: true,
      },
    },
  },
})

这里的判断顺序很重要：先用顶层 build.sourcemap 表达公共要求，再用 server.build.outDir 和 edge.resolve.noExternal 表达运行时差异。不要为每个环境复制整份配置，否则新增一个公共选项时很容易只改到 client。

继承关系要看清，optimizeDeps 不能一概下沉

Environment API 的继承并不是“顶层所有字段无条件复制”。官方文档说明，未特别标注时，新环境会继承顶层选项；但少数选项不适合作为服务端默认值，optimizeDeps 就是典型例外，它主要用于 client 的开发依赖预构建。

先保留兼容路径，再接入自定义运行时

如果项目只是 SPA 或普通 MPA，不必为了“使用新 API”强行引入环境对象；原有顶层配置仍然会作用于 client。SSR 项目可以先继续沿用现有 server API，等框架插件明确支持后，再把 server 或 edge 的差异迁入 environments。

更底层的 runtime provider 可以创建带默认值的自定义环境，甚至在开发阶段启动接近生产的进程或线程。它适合框架作者和运行时集成者，不适合作为普通业务项目的第一步。迁移时优先做三件事：列出每个环境允许使用的内置 API；为每个环境固定输出目录；把依赖解析失败记录到对应环境，而不是只看 client 的日志。

常见问题

Vite Environment API 是不是只能给 SSR 使用？

不是。SSR 是最容易感受到差异的场景，但浏览器、Node 和 Edge 并存的应用都可以用命名环境描述各自的约束。

为什么我配置了 server，却发现 optimizeDeps 没有按预期生效？

因为 optimizeDeps 主要面向 client 的开发预构建，不能把它当作服务端环境的通用继承项。服务端应检查自身的 resolve、build 和运行时依赖。

现在就应该把旧的 SSR 配置全部改成 environments 吗？

不必。官方文档仍强调兼容路径，Environment API 处于 release candidate 阶段。先让框架和插件完成适配，再按环境逐步迁移，通常比一次性重构更稳。