Vite项目兼容IE11实战：legacy插件与polyfill双产物配置

1. 动手之前先把“兼容 IE11”拆成三个判断题聊技术方案之前我更愿意先聊判断。因为“要兼容 IE11”这句话从需求方嘴里说出来含义差别巨大有时候它是验收报告上的一条硬指标有时候只是某位负责人拍脑袋的一句“万一有人用 IE 呢”。这两种情况的处置方式完全相反前者值得你花两周时间做降级和真机验证后者可能只需要在登录页加一句“建议使用现代浏览器”。贸然动手最常见的结局是花大力气做完兼容结果上线半年没有一个来自旧浏览器的访问记录反倒是 modern 产物的构建时间翻了一倍、包体多了几百 KB这笔账很难看。所以我在 Vite 项目上碰到这个需求时会先做三件事翻一下现网的访问日志和 UA 分布看旧内核的占比到底是多少确认这套系统对应的终端是谁在管员工有没有自己换浏览器的权限最后把框架版本和关键依赖过一遍判断技术上到底还救不救得回来。这三件事做完答案基本就浮出来了。绝大多数场景里超过八成的“必须兼容”最终都能被“给对应终端统一装个新浏览器”消化掉真正需要动代码的是剩下的那一小撮内网机器装不了新软件、嵌入式终端只有旧内核、或者页面被挂在别人系统的 iframe 里没法自己决定环境。这几种场景才轮到 Vite 的 legacy 方案登场。下面我把判断依据、方案选型、配置细节和踩过的坑一次讲清楚你可以照着这套流程走一遍。1.1 框架层不支持插件再全也白搭这是最容易忽略、也最伤人的一条。Vite 的vitejs/plugin-legacy解决的是“语法降级”和“运行时 API 缺失”这两个层面的问题它能把箭头函数、模板字符串、可选链、let/const、async/await这些东西统统编译成 ES5能给缺失的Promise、Map、Array.from补上实现。但它没法凭空造出一个Proxy。Proxy的get、set、has这些拦截器是引擎级别的行为用 ES5 语法根本无法模拟出等价效果——你可以在对象上定义 getter/setter但拿不到“属性不存在时被访问”这个时机也没法拦截整个对象的读写。所以任何依赖Proxy做响应式的框架在 IE11 上从原理层面就是死路。基于Proxy实现响应式的框架也就是近两年主流的新版前端框架无论你怎么配 polyfill页面都是不工作的可能不报错可能只渲染出静态部分但数据一变就再也不更新。能救的、且实际有人还在维护的组合大致是这几种技术栈类型在 IE11 上的可行性说明基于 Object.defineProperty 做响应式的老版本框架可行这是最典型的可救组合配合 legacy 插件基本能跑通老版本 React16 / 17基本可行需要额外补Map、Set、requestAnimationFrame等事件系统和调度器在旧引擎上会慢一些原生 TS / 轻量视图库 / 传统多页应用可行改造量最小也最容易验证新版基于 Proxy 的框架不可行引擎能力缺失不属于 polyfill 能覆盖的范围用了 Web Components Shadow DOM部分可行需要额外补template、CustomEvent等稳定性和性能都要打折这个表格的意义在于先花十分钟确认自己落在哪一行能省下两周的无效劳动。如果技术栈本身就落在“不可行”那一档正确的做法是回到需求侧去谈而不是硬着头皮上插件——硬上的结果往往是构建能过、页面能开、但业务逻辑随机失灵排查成本高到离谱。还有一类隐性风险是第三方依赖。哪怕你自己的业务代码写得很保守只要某个 UI 组件库、某个图表库、某个工具库内部用了Proxy或者Reflect整条链路就断了。所以确认框架之后还要把package.json里那几个体积最大的依赖过一遍看它们的文档有没有明确声明浏览器支持范围。这一步偷懒后面会以“某个页面白屏”的形式还回来。1.2 Vite 产物在旧浏览器白屏根子上是模块加载很多人第一次遇到这个问题时的反应是“是不是少引了什么 js”其实不是。Vite 默认的构建目标build.target是modules意思是产物面向“支持原生 ES Module 的浏览器”。它生成的 HTML 长这样script typemodule crossorigin src/assets/index-a1b2c3.js/script旧内核看到typemodule这个属性时会直接判定“我不认识这个脚本类型”然后跳过整段脚本连语法解析都不做控制台一声不吭。所以你看到的现象是HTML 正常返回、CSS 正常加载、页面骨架出现、但所有交互全死Network 面板里那个 js 文件状态是 200控制台干干净净。这个“静默失败”是排查路上最大的拦路虎因为没有任何错误信息指向它。即便退一步假设它肯执行这个脚本里面的语法也过不去默认产物里带着箭头函数、const、模板字符串、可选链?.、空值合并??、动态import()这些在旧引擎里会在解析阶段直接抛语法错误整个脚本一行都不执行。所以“Vite 项目要做旧浏览器兼容”这件事本质上是三件事的叠加模块加载层得有一个旧引擎能认识的加载方式把打包好的代码送进去语法降级层代码本身得能被旧引擎的解析器读懂运行时 API 层代码里用到的、但旧引擎没实现的内置对象和方法得提前补上。vitejs/plugin-legacy的价值就在于它把这三层一次性包了——它生成 SystemJS 格式的 legacy 产物、用 Babel 把 legacy 产物降级到 ES5、再按你的 targets 生成一份 polyfill 入口最后往 HTML 里注入探测脚本决定该加载哪一份。理解了这个分工后面看配置项就不会一头雾水。1.3 哪些能力注定补不回来得提前和需求方对齐这一点必须提前讲不然后面验收时扯皮。有些东西不是“没配好”而是根本补不了Proxy/Reflect的完整语义前面说过无法模拟。部分 CSS 特性CSS 自定义属性--var在旧引擎里完全不认display: grid的标准语法也不认position: sticky、object-fit、aspect-ratio、:is()、:where()全都不认。这些要么在构建期做静态替换要么改写成兼容写法没有运行时补救的余地。部分 DOM API 的行为差异比如classList.toggle(name, force)的第二个参数会被忽略classList.add()一次只能传一个参数Element.closest()压根不存在。这些能补但补丁质量参差不齐行为一致性需要自己验证。性能旧引擎的 JS 执行速度大概是现代引擎的十分之一到二十分之一SystemJS 的模块加载还有额外开销。一个在现代浏览器 1 秒内完成的首屏在旧内核上花 4 到 6 秒是常态。这个预期必须提前打预防针否则上线后会被投诉“卡到不能用”。把这三条摆到桌面上很多需求方自己就会重新评估优先级。剩下真正要做的我们再往下走。2. 方案设计语法降级、API 补齐、模块加载分开治2.1 只靠 Babel 不够但也不能全靠插件传统 Webpack 项目里的兼容方案大家都很熟babel-loaderbabel/preset-envcore-js3配合useBuiltIns: usage做按需注入。这套方案成熟的代价是构建慢——Babel 要把每一个模块都过一遍语法树项目大了动辄几分钟。Vite 的路子完全不一样。开发态它压根不打包浏览器原生import直接拿源码跑所以开发服务器启动是毫秒级的构建态它先用 esbuild 做语法转换和压缩esbuild 是 Go 写的比 Babel 快一个数量级再用 Rollup 做模块合并。整个链路里默认没有 Babel 的位置。这就是为什么你在 Vite 项目里找不到babel.config.js——它在正常路径上根本不需要。问题来了esbuild 的降级能力有边界它不支持降级到 ES5。你可以让它把 ES2020 转成 ES2015但再往下就不行了因为 esbuild 作者明确表示过 ES5 支持不在规划里。所以想在旧引擎上跑就必须在构建流程里额外插一个 Babel 阶段专门处理“给旧引擎用的那一份产物”。vitejs/plugin-legacy干的就是这件事它在构建的renderChunk阶段介入复制一份产物、用 Babel 降级到 ES5、改写成 SystemJS 格式、再单独生成 polyfill 入口。也就是说一个 Vite 项目配了这个插件之后最终产物是双份的现代浏览器拿现代版旧引擎拿降级版两者互不干扰。这个设计很讨巧——现代用户的体验一点没损失兼容成本只压在那部分真正需要的用户身上。2.2 插件内部到底做了哪些事一条条拆开看把插件的动作按时间顺序拆开能帮助你理解产物结构第一步生成 legacy chunk。Rollup 输出完正常产物后插件把每个 chunk 拿过来用 Babel内部预设相当于babel/preset-env的targets指向你配的浏览器范围做语法降级然后把 ESM 的import/export改写成 SystemJS 的System.register形式。动态import()会被改写成System.import()。第二步生成 polyfill chunk。插件用core-js-compat根据你的 targets 计算出“这些浏览器缺哪些内置模块”然后生成一个独立入口文件把对应的 core-js 模块全部 import 进来同时把 SystemJS 的运行时一小段 loader 代码也塞进去。默认情况下这个 chunk 叫polyfills-legacy-[hash].js。第三步改写 HTML。插件会把原来那个typemodule的 script 保留同时新增两个nomodule的 script一个指向 polyfill chunk一个指向 legacy 入口。legacy 入口不是直接script src加载的而是用># Vite 5 项目 npm i -D vitejs/plugin-legacy^5 terser # Vite 4 项目 npm i -D vitejs/plugin-legacy^4 terserterser是必须的。插件在处理 legacy chunk 时需要用 terser 做压缩esbuild 压不了 ES5 产物它把 terser 声明成了对等依赖你不装构建到那一步会直接告诉你找不到模块。这个报错信息还算清楚但第一次遇到容易懵——明明项目里一行 terser 配置都没有为什么要装它。core-js在新版插件里是内置依赖一般不用单独装如果你装的是较老的 2.x 版本可能会提示找不到core-js那时候手动补一个npm i -D core-js^3就行。判断方法很简单构建报错里出现Cannot find module core-js/...那就是缺了。如果你的项目里用了async/await并且目标里包含旧引擎大概率还需要regenerator-runtimenpm i regenerator-runtime它提供的是 Babel 把async/await编译成 generator 之后所需的运行时。虽然core-js现在也能覆盖一部分但显式加进additionalLegacyPolyfills更稳妥能避免一些边角情况下的regeneratorRuntime is not defined。3.2 一份可以直接抄的 vite.config 配置下面这份配置是我在多个项目里验证过的每一行都写了理由import { defineConfig } from vite import legacy from vitejs/plugin-legacy export default defineConfig({ plugins: [ legacy({ // 关键告诉插件要为哪些浏览器生成降级产物和 polyfill targets: [defaults, ie 11], // 默认 false设为 true 时插件会忽略项目里的 .browserslistrc ignoreBrowserslistConfig: false, // 是否生成 legacy chunk关掉就只剩 polyfill一般保持 true renderLegacyChunks: true, // true 表示按 targets 全量收集可能缺失的 core-js 模块 polyfills: true, // 是否也给现代产物生成一份 polyfill默认 false modernPolyfills: false, // 插件管不到的运行时用这个手动塞进 polyfill 入口 additionalLegacyPolyfills: [ regenerator-runtime/runtime, ], // 是否把 SystemJS 外置到全局内网环境建议保持 false externalSystemJS: false, }), ], build: { // 现代产物的语法下界防住一部分较老的现代浏览器 target: es2015, // 关键防止 esbuild 把 rgba() 压成 #rgba 导致旧引擎不认颜色 cssTarget: chrome61, // legacy chunk 由插件内部用 terser 处理这里显式声明更清晰 minify: terser, sourcemap: false, }, })几个地方需要展开讲。build.cssTarget这一行特别容易被忽略但它非常关键。Vite 用 esbuild 压缩 CSSesbuild 有个优化是把rgba(0, 0, 0, 0.5)压成#00000080这种八位十六进制写法。现代浏览器都认但旧引擎完全不认结果是颜色全部失效整站变白底黑字。这个 bug 的迷惑性在于样式表加载成功、选择器命中正常、DevTools 里能看到规则就是颜色不生效。cssTarget: chrome61的作用就是告诉 esbuild “按 chrome61 的能力来压缩”它就会放弃那个优化。build.target: es2015这一行跟 legacy 产物没有直接关系它管的是现代产物的下界。默认的modules对应的是[es2020, edge88, firefox78, chrome87, safari14]这一档产物里会保留可选链、空值合并这些语法。如果你的现代用户里还有人在用两三代以前的浏览器把它降到es2015会更保险。这个值设不设、设多少取决于你现代侧要覆盖的浏览器下限跟旧引擎那部分完全解耦。还有一条暗坑不要动build.rollupOptions.output.format。有些人从别的项目抄配置把 format 设成iife或者umd结果插件生成的 legacy chunk 全乱了System.register混着 iife 包装运行时报一堆语焉不详的错误。默认的 ESM 输出就对了剩下的交给插件。3.3 targets 该怎么写和 browserslist 谁说了算targets的取值格式跟 browserslist 一致可以写查询字符串也可以写数组。常见的几种写法// 写法一现代默认 旧引擎 targets: [defaults, ie 11] // 写法二精确到版本区间 targets: [chrome 49, ie 11, safari 10] // 写法三走 browserslist 配置插件参数留空 // 项目根目录 .browserslistrc 里写 defaults, ie 11这三种写法效果一样选一种就行别混着来。优先级规则是这样的如果插件参数里显式传了targets就用参数值没传的话插件去读项目里的 browserslist 配置.browserslistrc或者package.json的browserslist字段都找不到插件会报警告并按默认值处理。我倾向于把 targets 写在插件参数里理由是可见性。browserslist 配置常常是多人维护的某天有人为了加个前缀支持改了一行legacy 产物的范围也跟着变了等你发现问题时已经过去好几周了。写在 vite.config 里改的时候至少 diff 里看得见。另外有一个概念要分清targets同时影响语法降级的范围和polyfill 的收集范围但两者用的是不同的数据库。语法降级看的是 Babel 的babel/compat-datapolyfill 看的是core-js-compat。这两个库都会定期更新所以锁定插件的版本、定期升级依赖很重要——旧版本的兼容数据可能漏掉某些新出现的 API导致你以为补上了其实没补。3.4 产物结构长什么样三份文件怎么协作构建完之后dist目录大概是这个结构dist/ index.html assets/ index-a1b2c3.js # 现代产物ESM 格式 index-a1b2c3-legacy.js # 降级产物SystemJS 格式 polyfills-legacy-d4e5f6.js # polyfill 入口含 SystemJS 运行时 index-g7h8i9.cssindex.html会被改写成这样简化过script typemodule crossorigin src/assets/index-a1b2c3.js/script script nomodule crossorigin idvite-legacy-polyfill src/assets/polyfills-legacy-d4e5f6.js/script script nomodule idvite-legacy-entry >legacy({ targets: [ie 11], polyfills: [ es.promise, es.promise.finally, es.array.includes, es.object.entries, es.object.values, es.string.pad-start, ], })这种写法适合对体积极度敏感的项目但有个前提你得对代码里用到的每一个内置 API 心里有数包括第三方依赖里用到的。漏一个的后果是运行时抛xxx is not a function而且往往在某个低频路径上才触发测试很容易漏过去。我的建议是除非你已经在做体积预算并且有完整回归能力否则就用true多出来的几十 KB 换一个安心很值。modernPolyfills是另一个维度的东西它给现代产物也生成一份 polyfill。什么时候需要当你的 targets 里包含“支持 ES Module 但缺某些较新 API”的浏览器时。举个典型场景某个较老版本的桌面浏览器支持 ES Module但没有Array.prototype.flat、没有Object.fromEntries、Promise.allSettled也不存在。这类缺口build.target是管不了的它只转语法不管 API就得靠modernPolyfills: true或者显式列出模块名。4.2 core-js 管不到的得自己上手补core-js覆盖的范围是 ECMAScript 内置对象和方法加上一部分 Web 标准比如queueMicrotask、URL、URLSearchParams的较新版本。但下面这些东西它不管需要你自己装包缺失能力补丁包说明fetchwhatwg-fetch旧引擎完全没有且没有接近的替代不补就没法发请求IntersectionObserverintersection-observer懒加载、曝光埋点常用补丁是轮询实现性能开销明显ResizeObserverresize-observer-polyfill图表库、自适应布局常用Element.closest/matchesdom4或手写事件委托里很常见手写十行也能解决CustomEvent构造器custom-event-polyfill旧引擎有这个接口但不能new只能document.createEventPromise.prototype.finallycore-js 自带单独列出来是因为经常漏smoothscroll行为smoothscroll-polyfillscrollTo({ behavior: smooth })的参数对象形式不被支持补的方式有两种。一种是加进additionalLegacyPolyfills让插件打进统一入口additionalLegacyPolyfills: [ regenerator-runtime/runtime, whatwg-fetch, intersection-observer, ]另一种是在入口文件顶部手动import。两种方式的效果一样区别在于走插件配置的会进 polyfill chunk走手动 import 的会进业务 chunk。前者更清晰一眼看得出哪些是兼容补丁将来不做兼容了删起来干净后者更灵活可以做条件加载。我一般用前者因为半年后回来看代码vite.config里那一列补丁包比散落在入口文件里的 import 更好找。有一个细节要提醒additionalLegacyPolyfills里写的是模块路径不是 core-js 的模块名。写es.promise.finally会被当成 npm 包名去找然后报错找不到。这两类配置项名字很像很容易写串。4.3 CSS 的兼容比 JS 更容易被忽略JS 那边有 Babel 兜底CSS 这边全靠你自己。旧引擎在 CSS 上的坑密度不比 JS 小CSS 自定义属性完全不支持。--primary-color这种写法在旧引擎里就是无效声明所有var(--primary-color)都会失效表现为“颜色、间距、圆角全部丢失”。解决办法只有两个要么在构建期用 postcss 插件把变量静态求值替换掉前提是变量的值在构建时确定不依赖运行时切换主题要么干脆不用变量改回 SCSS 变量——后者的兼容性最好代价是失去了运行时换肤能力。// postcss.config.js export default { plugins: { postcss-preset-env: { stage: 2, features: { // 构建期把 var() 替换成实际值但只对静态可求值的情况有效 custom-properties: { preserve: false }, nesting-rules: true, }, }, autoprefixer: { overrideBrowserslist: [ie 11], }, }, }Flex 布局有一堆 bug。旧引擎的 flex 实现是早期的草案版本flex-basis加box-sizing: border-box会算错宽度、min-height在 flex 容器里不生效、百分比高度的子项会塌陷、flex: 1的简写在某些情况下被解析成flex: 1 1 0%之后表现异常。这些没有统一的解决方案只能靠autoprefixer加-ms-前缀打底再针对具体布局手写兜底。gap在 flex 容器里不生效。这个属性是后来才加进 flex 规范的旧引擎只支持 grid 里的gap。用了gap的地方得改成margin或者用:not(:last-child)加间距。选择器数量有上限。单个样式表里超过大约四千条规则之后后面的规则会被静默丢弃。大项目里这个问题很隐蔽——某个页面的某个角落样式突然失效你翻遍 CSS 也找不出原因。解决办法是按路由拆分样式文件别把所有东西塞进一个全局 css。style标签的规则数上限同理。如果你的构建产物是单个大 CSS 文件且规则数逼近这个量级就该考虑拆分了。4.4 体积和性能的账怎么算配完 legacy 之后构建产物的总体积大概会变成原来的 1.6 到 2.2 倍具体取决于业务代码量。多出来的部分主要是legacy chunk跟现代 chunk 差不多大但因为降级后代码更啰嗦通常还大 20% 到 40%、polyfill chunk压缩后 30KB 到 50KB、SystemJS 运行时十几 KB。构建时间也会明显变长因为多了一整轮 Babel 处理大项目从 40 秒变成 2 分钟是常见的事。这些成本只压在那部分真正用旧引擎的用户身上吗不是。服务端要存两份产物CDN 要分发两份构建流水线要多花时间。所以这件事的取舍不是在“用户体验”和“构建速度”之间做而是在“极小部分用户能不能用”和“所有人的工程成本”之间做。想让这个账好看一点有几个手段把 legacy 产物放到单独的部署路径。比如现代产物走主域名legacy 产物走一个独立目录通过base配置区分配合服务端 UA 判断做路由。这样 CDN 缓存的压力会小一些产物也便于单独清理。只在需要的时候构建。CI 里做两条流水线日常提交只出 modern 产物跳过 legacy 插件发版时再跑完整构建。用环境变量控制插件是否启用const enableLegacy process.env.BUILD_LEGACY 1 plugins: [ ...(enableLegacy ? [legacy({ targets: [ie 11] })] : []), ]裁掉用不到的 polyfill。如果你的业务代码里确实没用到Promise.allSettled、String.prototype.matchAll这类较新的 API可以试着把polyfills改成显式列表一个一个核对。这个工作枯燥但有效我做过一次polyfill chunk 从 46KBgzip降到了 21KB。别给旧终端加载现代产物的资源。图片、字体这类静态资源本身跟浏览器无关不用做双份。但如果用了srcset、picture、loadinglazy这些特性记得给旧引擎准备降级路径。5. 调试与验证让问题暴露在发布之前5.1 开发服务器救不了你构建产物才是真相vite dev走的是原生 ESM不经过 Babel、不生成 legacy chunk、也不注入探测脚本。也就是说在开发服务器上旧引擎永远打不开页面这不是 bug是设计如此。很多人第一次配 legacy 时改完配置就兴冲冲去开旧浏览器发现还是白屏然后开始怀疑人生。正确的验证姿势是三步# 1. 构建 npm run build # 2. 起一个静态服务器指向 dist npx vite preview --port 4173 # 3. 在目标浏览器里访问 http://localhost:4173vite preview起的是纯静态文件服务不做任何转换所以它返回的就是最终产物能真实反映线上行为。如果公司有测试环境更推荐直接部署到测试环境验证因为本地环境和服务端在压缩、缓存、MIME 类型上可能有差异。还要注意一点vite preview默认会加一些开发便利的响应头比如不缓存。线上如果配了强缓存验证时记得清缓存或者用无痕模式否则你看到的可能是上一版产物。5.2 怎么准备一个靠谱的旧浏览器环境现代机器上装不了那个浏览器所以基本靠虚拟机或者远程桌面。准备环境的几个要点用干净的系统镜像。别用同事那台装了一堆插件的机器环境不干净会导致误判。系统装好之后第一件事是确认浏览器版本号然后关掉自动更新有些环境里更新会被策略强制推送。装好之后先做一次基线测试。打开几个知名网站确认网络、DNS、代理配置正常。如果这些站都打不开说明是环境问题