在 vite 项目中配置旧浏览器兼容,核心做法是修改 vite.config.js 中的 build.target 选项并配合 @vitejs/plugin-basic-ssl 或原生 browserslist 设置。vite 默认使用现代构建目标(如 'es2020'),若需支持不支持 es modules 的旧版浏览器,应将 build.target 降级为 'esnext' 或具体版本如 'es2015',同时确保 rollupoptions 中正确配置了 output.format 和 legacy 插件。这样做会将代码转换为 commonjs 或更广泛的 es5/es6 语法,并自动注入必要的 polyfill。

Vite 默认构建目标与兼容性冲突
Vite 默认将 build.target 设置为 'es2020',这意味着它不会转换任何 ES2020+ 特性,也不会注入 Polyfill。如果用户浏览器不支持这些特性,页面会直接报错。要解决此问题,必须显式指定一个较低的构建目标,例如 'es2015' 或 'esnext',以触发 Rollup 的转译逻辑。

// vite.config.js
import { defineConfig } from 'vite';
import legacy from '@vitejs/plugin-legacy';
export default defineConfig({
plugins: [
legacy({
targets: ['defaults', 'not ie 11'],
polyfills: ['es.promise.finally', 'es/map'],
}),
],
build: {
target: 'es2015', // 关键:降级构建目标
rollupOptions: {
output: {
format: 'iife', // 针对旧浏览器输出 IIFE
},
},
},
});
上述配置中,legacy 插件负责生成兼容旧浏览器的脚本块,而 build.target 控制主包的转译级别。通过设置 target: 'es2015',Vite 会使用 esbuild 将代码编译为 ES2015 兼容语法,从而避免在现代浏览器中未处理的语法错误。
Legacy 插件的配置策略
仅修改 build.target 不足以完全兼容旧浏览器,因为某些 API(如 Promise.finally)需要 Polyfill。此时需引入 @vitejs/plugin-legacy 插件,该插件会自动检测目标浏览器并注入相应的 Polyfill 和兼容脚本。配置时需明确指定 targets 和 polyfills,以确保只注入必要的代码,避免体积膨胀。

// 安装依赖
// npm install @vitejs/plugin-legacy --save-dev
// vite.config.js 完整示例
import { defineConfig } from 'vite';
import legacy from '@vitejs/plugin-legacy';
export default defineConfig({
plugins: [
legacy({
targets: ['ie >= 11'], // 指定兼容 IE11+
polyfills: [
'es.promise',
'es.array.iterator',
'web.dom-collections.iterator'
],
}),
],
build: {
target: 'es2015',
minify: 'terser', // 旧浏览器需额外压缩
terserOptions: {
compress: {
drop_console: true,
},
},
},
});
在此配置中,legacy 插件会为 IE11 等旧浏览器生成单独的 chunk,并注入指定的 Polyfill。同时,minify: 'terser' 确保代码被进一步压缩,因为 esbuild 默认不处理旧浏览器的特定语法限制。通过这种方式,开发者可以精确控制兼容性范围,平衡性能与用户体验。
IE11 下模块加载失败的具体排查
当在 IE11 中访问应用时,常出现 SCRIPT1002: Syntax error 或 Object doesn't support property 'forEach' 错误。这通常是因为 build.target 未正确降级,或 legacy 插件未正确注入 Polyfill。需检查 vite.config.js 中是否同时设置了 target: 'es2015' 和 legacy 插件,并确保 polyfills 列表包含缺失的 API。
Java免费学习笔记:立即使用
解锁 Java 大师之旅:从入门到精通的终极指南











