跳到主要内容
api工厂
工程化

Vite 环境 API 与 SSR:多环境构建的新模型

api工厂资讯栏目 约 5 分钟阅读
本文由 AI 辅助生成,内容基于公开资讯整理改写,技术细节以官方文档为准。
内容摘要Environment API 让每个环境拥有独立模块图与解析条件,一份配置编排多端构建。本文覆盖 environments、buildApp 与 ModuleRunner 实战及跟进策略。

结论先行:Vite 的 Environment API 把「环境」抽象为一等公民,自 Vite 6 引入、在 Vite 7 中持续完善,用一份 environments 配置替代「客户端构建 + vite build --ssr 再跑一遍」的割裂流程;它主要面向框架与运行时集成者,业务项目通常经由上层框架间接受益,部分 API 仍标记为实验性,落地前以官方文档为准。 本文拆解新模型的核心概念与最小实战。

旧模型的痛点

传统 Vite SSR 项目要输出客户端与服务端两份产物,只能串行执行两次构建,或在插件里到处写 if (ssr) 分支。更深层的问题是单环境假设:客户端需要 browser 导出条件,服务端需要 node 条件,边缘运行时需要 worker 条件,而旧版共享同一套模块图与解析配置,跨环境状态互相污染,插件作者苦不堪言。Environment API 的答案是:每个环境拥有独立的模块图、解析条件与插件管线,物理隔离、共享底座。

environments:一份配置声明多环境

js
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 内完成编排:

js
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 可声明插件只在特定环境激活:

js
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 的框架方案,避免为用新特性而用新特性。

文章标签

ViteSSREnvironment API构建

相关产品

api工厂是面向开发者的开放 SaaS 平台:开箱即用的后台管理系统 + 全端 SDK,只需前端开发即可构建小程序、App、H5 与网站。

前端测试VitestPlaywright

前端测试金字塔:Vitest 单元测试 + Playwright E2E 落地

按测试金字塔划分单测、组件测试与 E2E 职责,给出 Vitest 与 Playwright 配置示例、真实商城链路用例、CI 分段策略与闪断治理方法。

工程化约 6 分钟阅读