Vite兼容IE11：Legacy插件与Polyfill配置实战

Vite 项目要兼容 IE11绕不开的就是 Legacy 插件加 Polyfill 这套组合拳。这套配置我从 Vite 2 时代一直配到 5前后在六七个交付型项目里落地过踩过的坑足够写满两页纸。很多人第一次配的时候会遇到两个极端要么按官方文档抄了一段配置结果在老浏览器里还是白屏要么把 core-js 全量塞进去首屏体积直接翻倍被业务方追着问为什么新浏览器打开也变慢了。这篇内容解决的就是这两件事怎么把vitejs/plugin-legacy配对、配全以及 Polyfill 到底该按什么粒度补。它适合正在做政企交付、内部系统、老旧设备适配的前端同学也适合刚接手一个历史项目、发现构建工具从 webpack 换成了 Vite 但兼容要求没变的人。哪怕你只是想搞清楚为什么 dev 环境下 IE11 永远打不开看完也能明白背后的机制。1. 兼容 IE11 这件事先算清楚值不值得做1.1 什么情况下这块骨头必须啃先说结论如果一个项目是纯 C 端、用户以移动端为主那我劝你直接放弃 IE11把精力放在性能和体验上。但现实里还有相当一部分场景绕不开——内网办公系统、需要装在特定终端上的业务工具、对接过某些老设备的后台管理平台这些地方的浏览器版本不由你决定甚至不能升级。我接过一个项目交付方明确在合同里写了需在目标终端自带的浏览器上正常运行那时候没有商量的余地只能硬着头皮做降级。判断要不要做兼容我一般看三个信号需求文档或验收标准里有没有明确写明浏览器版本要求、用户侧有没有可统计的访问数据、以及技术栈本身是否还救得回来。第三条最容易被忽略——如果你的项目用了某个基于Proxy实现响应式的框架或者引入了大量只提供 ESM 产物的依赖那这不是配置问题是选型问题再怎么调 Legacy 插件也救不回来只能换技术栈或者推动升级终端。反过来说如果你的项目是 Vue 2、React 17 这类运行时本身就向下兼容的组合加上业务代码写得比较规矩那 Legacy 插件基本能让你在半天内跑通。这个前提很重要我见过太多人在一个先天不支持老浏览器的框架上折腾构建配置折腾一周也没结果方向一开始就错了。1.2 代价清单体积、构建时间与后续维护兼容不是免费的我习惯在动手前把这笔账摊开给相关方看避免后面被质疑。代价主要落在三个地方。第一是产物体积。Legacy 方案的本质是同一份代码出两份一份给现代浏览器语法新、体积小一份给老浏览器语法旧、还带一堆 polyfill。老浏览器那份通常比现代那份大 40% 到 80%具体取决于你用了多少新语法和需要补多少 API。这不是浪费因为老浏览器只会下载老那份但它确实让构建目录看起来体积翻倍。第二是构建时间。Legacy 构建要多跑一遍 Babel 转译还要额外压缩一次。我在一个中等规模项目上实测过构建时间从 28 秒涨到 51 秒接近翻倍。如果项目开了 CI每次提交都跑构建这个成本会累积。我的做法是把 Legacy 构建拆到单独的 npm script 里日常开发只跑现代构建只有在提测和发版时才跑完整构建。第三是长期维护成本。一旦引入 Legacy你写的每一行代码都要在心里过一遍这段在老浏览器上行不行。比如随手写个Array.prototype.at()、用个structuredClone、或者在 CSS 里写个gap都可能在老浏览器上悄悄出问题。这种心智负担是持续的不是配完就结束了。所以我的建议是能用工程手段解决的问题自动 polyfill、lint 规则、构建检测就尽量自动化别指望靠人记。2. 整体思路双构建 按需 Polyfill 是怎么设计的2.1 三条主流路线对比与选型结论在 Vite 体系下做老浏览器兼容大致有三条路可走我把它们的实际表现整理成了下面这张表。方案做法优点致命短板适用场景纯 Babel 降级把build.target设成es5全局 Babel 转译配置简单产物单一Vite 开发态仍是原生 ESM老浏览器 dev 下必白屏polyfill 全靠手写现代浏览器加载完整降级产物性能白亏几乎不推荐单构建 手动 polyfill保留现代构建运行时手动引入 core-js体积可控语法降级完全不管老浏览器解析即报错只差 API 不差语法的极端情况双构建Legacy 插件现代产物 老浏览器产物并存按能力分发语法、API 双管齐下现代浏览器零损失构建时间与产物体积增加部分能力无法降级绝大多数需要兼容老浏览器的 Vite 项目结论很清楚除非你的兼容需求极轻比如只差一两个 API否则就走第三条路。Vite 官方的vitejs/plugin-legacy做的就是这件事它不是简单地把 Babel 挂上去而是完整实现了双份产物 能力检测 按需加载这一整套逻辑。这里有个认知需要先纠正很多人以为 Legacy 插件的作用是让老浏览器能跑 ESM其实不是。它根本不打算让老浏览器跑 ESM而是绕过 ESM用 SystemJS 这种运行时加载器去加载老格式的模块。理解这一点后面很多现象就顺了。2.2 plugin-legacy 的内部工作机制拆解这个插件在构建期和产物注入期分别做了几件事我按执行顺序拆一下理解了流程你排查问题会快很多。第一步是在构建阶段多做一轮 rollup 输出。现代构建照常跑输出typemodule的入口脚本同时插件会以es5附近的目标再跑一遍产物渲染把每个 chunk 用 Babel 转成老语法输出一套名字带-legacy后缀的 chunk并且模块格式换成 SystemJS。这一步是语法降级。第二步是生成 polyfill chunk。插件会根据targets匹配需要补的 API从core-js里挑出来单独打成polyfills-legacy-[hash].js。同时会带上一份 SystemJS 的运行时。这一步是API 降级。第三步是往 HTML 里注入分发逻辑。注入的东西大致长这样结构示意实际 hash 和变量名会变script nomodule !function(){ // 能力检测判断当前浏览器是否支持动态 import、import.meta 等新特性 // 支持则什么都不做交给 typemodule 的脚本 // 不支持则注入下面两个 nomodule 脚本 }() /script script nomodule src/assets/polyfills-legacy-a1b2c3.js/script script nomodule idvite-legacy-entry>npm i -D vitejs/plugin-legacy^5.4.0 terser core-js^3.37.0装完之后建议立刻在package.json里把vitejs/plugin-legacy的版本号上的^去掉锁死到具体版本。原因很实在这个插件的补丁版本偶尔会调整注入脚本的检测逻辑导致某些边缘浏览器从现代分支掉到 legacy 分支或者反过来。这类变化不会写进你的代码但会改变线上表现出问题时极难定位。锁死版本能让昨天还好好的今天就不行了这类事故少一大半。core-js也建议锁。它的版本决定了能补哪些 API3.20 之前的版本对某些较新的 API 支持不全。3.2 一份可直接抄的核心配置下面这份配置是我在多个项目里反复验证过的可以直接拿去改。// vite.config.js import { defineConfig } from vite import legacy from vitejs/plugin-legacy export default defineConfig({ base: /your-sub-path/, // 部署在子路径时务必写对否则 legacy 脚本 404 build: { target: es2015, // 现代分支的降级目标别设太高 cssTarget: chrome61, // 防止 esbuild 把 CSS 语法降级出问题 minify: terser, // 统一用 terser避免两套压缩器行为不一致 sourcemap: false, // legacy 产物带 sourcemap 体积会非常夸张 }, plugins: [ legacy({ targets: [ie 11], renderLegacyChunks: true, modernPolyfills: false, polyfills: true, additionalLegacyPolyfills: [regenerator-runtime/runtime], }), ], })逐项说一下为什么这么设。build.target: es2015是个折中。设成默认的modules约等于 es2020会让现代产物用到较新的语法虽然 legacy 分支会再转一遍但如果某些语法在 esbuild 阶段就被优化成了老浏览器更难处理的形式比如把类编译成某些奇怪结构Babel 那边会更吃力。设成es2015能让 esbuild 少做激进优化给后面的 Babel 留出更干净的输入代价是现代产物稍微大一点点。我在实际项目里对比过gzip 后差距通常在 3% 以内换来的是构建稳定性值。cssTarget: chrome61这一项很多人不知道。esbuild 在处理 CSS 时也会按目标降级比如把#RGBA十六进制色值展开成rgba()、把一些简写拆开。如果不设它会跟着build.target走可能写出一些在老浏览器上表现异常的 CSS。设成chrome61是个通用安全值。minify: terser的理由和上面类似两套构建用同一个压缩器行为一致出 bug 时只需要怀疑一处。Vite 5 默认的 esbuild 压缩更快但它对 legacy 分支本来也不生效插件内部走 terser所以统一设置反而更省心。additionalLegacyPolyfills: [regenerator-runtime/runtime]这一行是保险。Babel 把async/await降级成生成器之后需要regenerator-runtime来支撑。大多数情况下自动检测能补上但在某些依赖组合下会漏导致老浏览器报regeneratorRuntime is not defined。手动加上这一行成本是 2KB 左右能省掉一类非常难查的错误。3.3 targets 到底该怎么写一个被大量抄错的参数这一点我必须单独拎出来讲因为我见过太多人在这里翻车。官方文档示例里有一行是targets: [defaults, not IE 11]注意看那是排除IE11 的写法意思是支持主流浏览器的默认集合但不包含 IE11。这个示例是放在如何不兼容 IE11的语境下的。但我在各种文章和博客里见到无数人直接把它复制过来然后配完发现 IE11 还是白屏跑来问为什么插件没生效。要兼容 IE11正确写法是legacy({ targets: [ie 11], })或者更明确一点legacy({ targets: [defaults, ie 11], })第二种写法更推荐因为它同时兼顾了其他老浏览器比如某些国产内核的旧版本覆盖面更全。ie 11单独列出来的好处是浏览器列表解析器不会因为你同时列了defaults就把 IE11 从结果里剔除——有些版本的 defaults 本身就不含 IE11两个一起写才是稳妥的。还有一个参数ignoreBrowserslistConfig默认false意思是插件会去读项目根目录的.browserslistrc或package.json里的browserslist字段。如果你的项目里恰好有这么个配置很常见从 webpack 时代带过来的它会和插件里的targets合并。合并结果可能和你预期不一样比如.browserslistrc里写了not dead就可能把 IE11 又排除掉。排查这类问题的办法很简单在配置里临时打开ignoreBrowserslistConfig: true如果 bug 消失了就说明是 browserslist 配置在捣乱。确认之后要么统一到一处配置要么把这个开关常开。我个人的习惯是常开把兼容目标集中写在vite.config.js里避免配置文件散落各处、改了一处忘了一处。3.4 构建产物结构确认怎么验证配置真的生效了配置写完跑一次vite build然后去看dist目录和index.html。这一步一定要做别跳过因为配置写了但没生效是这个插件最常见的问题。正常的产物目录里应该有这些东西一堆带 hash 的现代 chunk、一堆后缀为-legacy的老 chunk、一个polyfills-legacy-[hash].js。如果只看到现代 chunk说明插件根本没跑起来去检查插件是不是真的加进plugins数组了、有没有被其他插件覆盖。再看dist/index.html应该有这几类标签现代入口的script typemodule crossorigin src...、一段nomodule的内联检测脚本、polyfills-legacy的引用、还有一个带>// src/main.js 最顶部 import core-js/stable // 最粗暴的全量补丁慎用 // 或者精确到模块 // import core-js/es/array/from // import core-js/es/object/entries // import core-js/es/promise/finally // import core-js/es/string/pad-start // import core-js/web/url-search-paramscore-js/stable会带来接近 90KB gzip 的体积这是全量方案除非你的目标浏览器老得离谱否则别用。精确引入能把体积压到 10KB 以内代价是你要自己维护一份清单。我一般会准备这么一份清单写在文档里团队共用API常见触发场景补丁路径Promise.finally请求封装里用.finally收尾core-js/es/promise/finallyObject.entries/values遍历配置对象core-js/es/object/entriesArray.prototype.includes列表判存在core-js/es/array/includesString.prototype.padStart数字补零、编号格式化core-js/es/string/pad-startURLSearchParams处理查询参数core-js/web/url-search-paramsElement.closestDOM 向上查找core-js/web/dom-collectionsNodeList.prototype.forEach遍历 DOM 集合core-js/web/dom-collections注意Element.closest和NodeList.forEach这两项经常被漏掉因为现代浏览器里写起来太自然了代码审查时根本不会有人觉得有问题。建议在项目里加一条 ESLint 规则把这类 API 列为 warning逼开发者显式确认。4.4 体积实测三套策略的对比我在一个中等规模的后台项目上做过实测同一个代码库用三种 polyfill 策略构建记录 gzip 后的产物体积。数据仅供参考你的项目结构不同绝对值会差很多但比例关系有参考价值。策略legacy 产物总量gzip相对基线说明polyfills: false 零手动补丁约 118KB基线体积最小但老浏览器基本必炸polyfills: true自动检测约 152KB29%推荐起点覆盖绝大多数场景自动检测 additionalLegacyPolyfills约 158KB34%我的常用配置加了保险core-js/stable全量约 243KB106%体积翻倍仅极端场景使用从数据能看出来从自动检测升级到自动 手动兜底只增加了 6KB 左右但能消掉一整类难以排查的运行时错误性价比极高。而全量方案多出来的 85KB换来的只是极少数边缘 API 的覆盖完全不值。这里还有个容易忽略的点legacy 产物只会被老浏览器下载。现代浏览器走的是typemodule分支根本不会请求那些nomodule脚本。所以增加 legacy 体积不会拖慢主流用户的加载速度只会增加构建目录的磁盘占用和 CDN 的存储成本。想清楚这一点你在做体积取舍时会从容很多。5. 真机上必踩的坑语法过了不代表页面能跑5.1 CSS 层的降级处理JS 转译完成只是第一步页面在老浏览器上能不能看很大程度上取决于 CSS。我在实际项目里遇到过的 CSS 问题比 JS 问题更多也更隐蔽因为 JS 报错至少控制台会告诉你CSS 不生效是静默的。最常见的三类变量不解析导致整块样式失效、布局属性不支持导致元素错位、伪类和选择器不支持导致样式选择器整体被丢弃。第三类最坑因为现代浏览器会跳过不认识的选择器但保留后面的规则而老浏览器可能会把整条规则连同后面的都丢掉导致一大片样式集体失踪。我一般的处理方式是加一层 postcss 处理链路在构建期把这些都展开掉// postcss.config.js export default { plugins: { postcss-custom-properties: { preserve: false }, postcss-color-mod-function: {}, postcss-gap-properties: {}, autoprefixer: { overrideBrowserslist: [ie 11] }, }, }preserve: false是关键它会把变量直接替换成计算后的值不保留原来的var()声明。这样老浏览器拿到的是纯静态的 CSS不需要理解变量。还有一个实操建议在项目里写 CSS 时养成变量只用来做主题、不用来做布局计算的习惯。主题切换在老浏览器上本来就要另做一套方案而布局相关的值如果全用变量展开后会产生大量重复样式体积会失控。5.2 第三方依赖不听话怎么治第三方依赖是兼容路上最大的变数。你在自己的代码里再小心只要引入了一个用了新语法、新 API 或者是纯 ESM 发布的包就可能前功尽弃。纯 ESM 包的问题最直接老浏览器环境下legacy 构建走 SystemJS如果某个依赖只提供 ESM 产物且没有可被正确处理的入口字段打包时就会出问题。判断办法是看dist里的 legacy chunk 是否有异常大的体积或者构建时的警告。新语法和 API 的问题相对好处理。Legacy 插件在渲染阶段是对最终 chunk 整体做 Babel 转译的所以node_modules里的代码语法也会被降级。但 API 不会——依赖里如果用了Proxy、WeakRef、BigInt这类无法 polyfill 的东西只能换包。我的处理顺序是这样的先用构建日志和产物分析找出可疑依赖也就是那些体积大、语法新的包。对每个可疑依赖查它有没有提供兼容构建比如dist/xxx.legacy.js或者browser字段指向老版本产物。如果有通过resolve.alias指向兼容版本。如果没有且无法降级评估替换方案。实在换不掉的隔离到一个懒加载的模块里保证主流程不受影响。resolve.alias这招很实用举个例子resolve: { alias: { some-lib: some-lib/dist/some-lib.umd.min.js, }, }这样开发时用的还是 ESM 版本tree-shaking 更好构建时可以按需切换。注意 alias 是全局生效的切换前确认 UMD 版本的导出结构一致否则会出现运行时 undefined的问题。5.3 dev 环境为什么永远是白屏这个问题我被问过太多次了答案很简单Vite 的开发服务器不提供降级产物。Vite 的核心优势是开发态不打包它把源码作为原生 ESM 直接丢给浏览器。原生 ESM 只有现代浏览器支持IE11 根本不认识typemodule所以开发服务器返回的 HTML 在老浏览器上就是一片空白。这不是配置问题是 Vite 的设计决定的官方也没有打算改。所以验证兼容性只有一条路vite build之后用vite preview起一个静态服务器用老浏览器访问。这个流程必须写进团队的联调规范不能指望开发时看着好好的上线应该也没问题。# 构建并预览验证兼容性的唯一靠谱方式 npx vite build npx vite preview --port 4173如果觉得每次手动跑麻烦可以在package.json里加个脚本{ scripts: { build:legacy: vite build, preview:legacy: vite preview --port 4173 } }还有个提升效率的办法在本地用虚拟机或独立设备跑一个老浏览器环境配置好固定 IP 访问需要验证时直接刷。别用各种模拟老浏览器的工具它们模拟的是 UA 和部分特性模拟不了真实的引擎行为很多问题是模拟不出来的。5.4 CSP 与 nomodule 的边界情况如果你的项目部署环境有内容安全策略CSP需要注意 Legacy 插件注入的是内联脚本。默认情况下 CSP 会拦截内联脚本导致能力检测逻辑不执行页面在老浏览器上直接白屏而且在现代浏览器上也看不出异常因为现代分支不依赖那段脚本。解决办法有两种给内联脚本加 nonce或者把相关 hash 加入白名单。Vite 的 HTML 处理插件支持通过html相关配置注入属性具体的做法取决于你用的 HTML 处理方案。这是个需要和部署方提前对齐的事项别等上线才发现。还有一种边界情况某些企业内部的浏览器兼容模式会对nomodule属性的处理有 bug导致本该执行的老脚本被跳过。这类问题没法从代码层面通用解决只能靠具体环境测试。我一般的处理是在检测脚本里加一个兜底如果一段时间后页面主容器仍然是空的就主动加载 legacy 入口。这段代码有点脏但在极端环境下确实能救命。6. 排查实录白屏、报错与定位顺序6.1 常见报错速查表老浏览器上的报错信息往往很难懂我整理了一份对照表都是我在实际项目里遇到过的。报错信息根因定位与修复SCRIPT1002: 语法错误老浏览器解析到新语法确认-legacychunk 是否真的被加载多半是 HTML 注入没生效Promise 未定义polyfill chunk 未加载或加载顺序错检查polyfills-legacy的script是否在入口之前System 未定义SystemJS 运行时缺失检查是否设了externalSystemJS: true但没手动引入regeneratorRuntime is not definedasync 降级后缺运行时把regenerator-runtime/runtime加进additionalLegacyPolyfills对象不支持此属性或方法缺少某个具体 API根据报错位置反查调用的方法针对性补 polyfill页面空白但无报错CSS 变量失效或脚本未执行先看 Network 里 legacy 脚本是否 404再看样式计算值无法获取未定义或 null 引用的属性某个全局对象缺失常见于window.matchMedia、IntersectionObserver等最后一条值得展开说。matchMedia、IntersectionObserver、ResizeObserver这几个 API 在老的 DOM 操作里经常被直接调用而不做存在性判断。它们不是 ES 标准的一部分core-js的stable入口里也不一定包含。IntersectionObserver有独立的 polyfill 包可以手动引入ResizeObserver同理。这类补丁建议在入口文件里统一处理用特性检测包一层缺失时提供一个空实现的降级版本至少保证不崩。6.2 白屏排查的三段式定位法白屏是最让人抓狂的现象因为没有任何信息。我摸索出一套三段式的排查顺序基本能在十分钟内定位到问题出在哪一层。第一段看网络层。打开开发者工具的网络面板刷新页面看有没有 404。重点看三个东西现代入口、legacy 入口、polyfill chunk。如果 legacy 入口 404八成是base配错了或者部署时目录结构变了。如果压根没有发起请求说明内联检测脚本没执行回去查 CSP 或者 HTML 注入。第二段看脚本层。在网络面板里确认 legacy 脚本确实下载成功了再看控制台有没有语法错误。有语法错误说明 legacy 产物里的语法还是太新通常是某个依赖没被正确处理或者targets配得不对。这时候可以去dist里搜一下 legacy chunk 的关键词比如搜箭头函数、const、反引号如果还能搜到大量说明转译没覆盖到。第三段看执行层。脚本都加载了、也没报错但页面还是白的那问题多半在初始化逻辑。在入口的第一行打个日志看执行到哪一步停了。这类问题常见于某个 API 缺失导致的静默失败比如前面说的matchMedia。这时候可以在入口里加一段全局错误捕获把错误直接显示到页面上比翻控制台快。// 临时的排查辅助代码上线前删掉 window.onerror function (msg, url, line, col, err) { document.body.innerHTML pre stylefont-size:14px;padding:20px; msg: msg \n url: url \n line: line : col \n stack: (err err.stack) /pre }这段代码在正常项目里当然不能留但在排查期非常有效尤其是目标终端上没法打开开发者工具的时候——把错误画到页面上拍个照就能定位。6.3 我在实际项目里踩过的几个坑第一个坑是子路径部署。本地预览一切正常部署到测试环境后老浏览器白屏现代浏览器也白屏。排查了半天发现是base没配HTML 里引用的脚本路径是/assets/...而实际部署在/admin/下全部 404。这个错误的诡异之处在于现代浏览器也会挂所以第一反应会以为是构建坏了。修法就是把base写对并且在 CI 里加一步产物路径检查。第二个坑是动态导入的降级。项目里有几个路由做了懒加载现代分支一切正常老浏览器上点进去就白。原因是某个懒加载模块里用了一个只在新环境可用的特性而这个模块被打成了独立 chunklegacy 分支下这个 chunk 的加载逻辑走的是 SystemJS 的路径错误信息被吞掉了。定位办法是在入口处给System.import加错误回调把失败信息打出来。这件事教会我一件事所有异步加载的模块都要单独在老浏览器里点一遍不能只测首屏。第三个坑是压缩器不一致导致的诡异问题。早期为了构建快现代分支用默认压缩legacy 分支走 terser。结果有一段用了try/catch包着可选链的代码两个压缩器处理后的语义不一致老浏览器上报了个完全不相干的错误。后来统一成 terser 就没再出现。这件事的教训是两套产物尽量共用同一套工具链配置减少变量。第四个坑是第三方 UI 库的样式。JavaScript 全过了但某些组件的样式在老浏览器上错位得厉害原因是用了一些只在现代浏览器生效的布局属性。这类问题没有通用的修法只能逐个组件对照检查。我的做法是列一个高风险组件清单把涉及复杂布局弹层、表格固定列、虚拟滚动的组件挑出来逐个在老浏览器上验证一遍。这个工作量不小但比上线后被业务方一个个截图反馈要高效得多。第五个坑也是最容易被忽略的构建缓存。开了构建缓存之后改了targets配置但产物没变因为缓存命中了。这个坑特别隐蔽会让你以为配置不生效。遇到改了配置没反应的情况先清缓存再试能省掉大量自我怀疑的时间。如果你想进一步降低维护成本可以在 CI 里加一个产物校验脚本构建完成后自动检查dist/index.html里是否存在nomodule脚本、是否存在polyfills-legacy引用、legacy chunk 数量是否大于零。这三项任一不满足就抛错把配置被误删或被其他插件覆盖这类问题拦在发版之前。这套检查我加进去之后因为构建配置问题导致的线上事故基本归零了。