结论先行:Vite 的 Environment API 把「环境」抽象为一等公民,自 Vite 6 引入、在 Vite 7 中持续完善,用一份 environments 配置替代「客户端构建 + vite build --ssr 再跑一遍」的割裂流程;它主要面向框架与运行时集成者,业务项目通常经由上层框架间接受益,部分 API 仍标记为实验性,落地前以官方文档为准。 本文拆解新模型的核心概念与最小实战。
旧模型的痛点
传统 Vite SSR 项目要输出客户端与服务端两份产物,只能串行执行两次构建,或在插件里到处写 if (ssr) 分支。更深层的问题是单环境假设:客户端需要 browser 导出条件,服务端需要 node 条件,边缘运行时需要 worker 条件,而旧版共享同一套模块图与解析配置,跨环境状态互相污染,插件作者苦不堪言。Environment API 的答案是:每个环境拥有独立的模块图、解析条件与插件管线,物理隔离、共享底座。
environments:一份配置声明多环境
import { defineConfig } from 'vite';
export default defineConfig({
environments: {
client: {
build: {
outDir: 'dist/client',
rollupOptions: { input: 'src/entry-client.js' },
},
},
ssr: {
resolve: { conditions: ['node'] },
build: {
outDir: 'dist/server',
rollupOptions: { input: 'src/entry-server.js' },
},
},
},
});公共配置留在顶层,环境差异写进各自块内。需要第三端(如边缘 Worker)时再加一个环境块,声明 worker 解析条件即可,不再需要第三份配置文件与第三条构建脚本。
builder.buildApp:编排构建时序
多环境构建常有顺序要求:先出客户端产物与 manifest,再构建注入资产信息的服务端入口。新的 buildApp 钩子让框架在一次 vite build 内完成编排:
export function ssrCoordinator() {
return {
name: 'ssr-coordinator',
async buildApp(builder) {
await builder.build(builder.environments.client);
await builder.build(builder.environments.ssr);
},
};
}无依赖关系的环境可以用 Promise.all 并行构建。这取代了过去用 npm scripts 串联多次构建的做法,构建上下文不再割裂。
插件的环境感知
插件钩子中的 this.environment 直接给出当前环境,applyToEnvironment 可声明插件只在特定环境激活:
export function edgeGuard() {
return {
name: 'edge-guard',
applyToEnvironment(env) {
return env.name === 'edge';
},
transform(code, id) {
if (/node:fs/.test(code)) {
this.error('边缘环境禁止引入 Node 原生模块: ' + id);
}
},
};
}开发态则通过 ModuleRunner 在宿主进程内执行服务端模块:createServerModuleRunner(server.environments.ssr) 拿到 runner 后 import 入口即可渲染,配合 isRunnableDevEnvironment 判断环境类型,SSR 热更新与客户端 HMR 可以在同一个开发服务器内联动。迁移时注意:旧版顶层 build.ssr 与 ssr 配置已不推荐,应改写为 environments.ssr 显式块;插件若生成虚拟模块,建议在模块 id 中带上环境名前缀,避免多环境缓存互相覆盖。
业务项目要不要跟
直接写 environments 配置的多是框架作者;业务项目更应关注上层框架是否已基于新 API 升级。另一个现实判断是:多数商城、管理后台类应用用 CSR 已足够,把 SEO 需求交给内容页静态化即可。例如基于 api工厂 SDK(https://www.it120.cc/sdk/index.html)构建的商城前端,商品、订单数据走现成接口,开源的 vueMinishop 等模板(https://www.it120.cc/help/uq920k.html)均为客户端渲染,无需引入 SSR 复杂度;确有首屏与收录诉求时,再评估基于 Environment API 的框架方案,避免为用新特性而用新特性。
文章标签
相关产品
api工厂是面向开发者的开放 SaaS 平台:开箱即用的后台管理系统 + 全端 SDK,只需前端开发即可构建小程序、App、H5 与网站。