低版本浏览器兼容方案：IE11 适配 ES6 语法与 CSS 新特性

面向仍需支持 IE11 的项目，目标是在不牺牲核心可用性的前提下，对 JS 的 ES6 语法与常用 Web API、以及 CSS 的现代特性做可控的转译、垫片与降级。本文给出工程实践、常见坑位与测试清单，帮助前端团队稳定交付。

兼容原则

明确范围：页面可正常加载、主要交互可用、视觉允许有限降级
优先工程化：构建期转译为主，运行期垫片为辅
面向能力：特性检测优先于 UA 检测，按需启用降级
可回归：用自动化与手动清单覆盖关键路径，避免隐性回归

JavaScript：ES6 转译与垫片

Babel 基础配置

目标版本：ie 11
按需垫片：useBuiltIns: "usage" 搭配 core-js@3
异步支持：regenerator-runtime 用于 async/await

.browserslistrc

复制代码

> 0.5%
last 2 versions
ie 11
not dead

babel.config.js

复制代码

module.exports = {
  presets: [
    [
      '@babel/preset-env',
      {
        targets: { ie: '11' },
        useBuiltIns: 'usage',
        corejs: 3
      }
    ]
  ]
}

Webpack 示例（按需转译第三方依赖）

复制代码

module.exports = {
  module: {
    rules: [
      {
        test: /\.(js|mjs)$/,
        include: [
          path.resolve(__dirname, 'src'),
          path.resolve(__dirname, 'node_modules/some-esm-lib')
        ],
        use: {
          loader: 'babel-loader',
          options: {
            presets: [
              [
                '@babel/preset-env',
                { targets: { ie: '11' }, useBuiltIns: 'usage', corejs: 3 }
              ]
            ]
          }
        }
      }
    ]
  }
}

常用垫片与注意事项

语法转译：class、arrow function、template string、destructuring、for-of 均由 Babel 处理
基础 API：Promise、Map/Set、Object.assign、Array.from、String.includes 等由 core-js 自动注入
异步能力：async/await 依赖 regenerator-runtime，入口文件引入 import 'regenerator-runtime/runtime'
Fetch：使用 whatwg-fetch 或通过 axios 规避原生缺失
URL 与搜索参数：URL、URLSearchParams 在 IE11 缺失，按需引入 core-js/web/url
NodeList：IE11 不支持 NodeList.forEach，由 core-js 或自行降级循环
迭代器：对非数组对象进行 for-of 需要 Symbol.iterator，确认 core-js 注入到全局
第三方库：部分库发布 ESM 产物，需加入转译白名单，避免产出 ES6 语法进入最终包

TypeScript 项目

tsconfig.json

复制代码

{
  "compilerOptions": {
    "target": "ES5",
    "module": "ESNext",
    "lib": ["ES2015", "DOM"],
    "downlevelIteration": true,
    "esModuleInterop": true,
    "skipLibCheck": true
  }
}

使用 Babel 承担 TS 到 ES5 的最终降级，或 ts-loader 输出后再经 Babel
开启 downlevelIteration 确保 for-of 与展开操作在对象/Map/Set 上正确运行

CSS：新特性前缀与降级

PostCSS 与 Autoprefixer

postcss.config.js

复制代码

module.exports = {
  plugins: [
    require('postcss-preset-env')({
      stage: 3,
      autoprefixer: { grid: 'autoplace' },
      features: { 'custom-properties': false }
    })
  ]
}

根据 .browserslistrc 自动补齐前缀，启用 grid: 'autoplace' 为 IE11 生成 -ms-grid
关闭 custom-properties 的编译以便用运行时垫片或手动降级

Grid 降级策略

优先使用 @supports 做条件启用，默认使用 Flex 作为基础布局

.container { display: -ms-flexbox; display: flex }
@supports (display: grid) {
.container { display: grid; grid-template-columns: repeat(12, 1fr) }
}
需要 IE11 的 -ms-grid 时，显式定义行列并用手动定位

.wrapper { display: -ms-grid; -ms-grid-columns: 1fr 1fr; -ms-grid-rows: auto }
.item-a { -ms-grid-column: 1; -ms-grid-row: 1 }
.item-b { -ms-grid-column: 2; -ms-grid-row: 1 }

Flexbox 兼容细节

同时声明 display: -ms-flexbox; display: flex
使用 -ms-flex: 1 0 auto 对齐 IE11 的伸缩语法
避免 min-height: 0 带来的溢出问题，必要时显式设置容器尺寸

CSS 变量与其他特性

CSS 变量：在入口处启用 css-vars-ponyfill
<script src="https://unpkg.com/css-vars-ponyfill@2"></script> <script>cssVars({ onlyLegacy: true })</script>
position: sticky：用 stickyfilljs 针对 IE11 进行模拟
object-fit: cover：用包裹元素加 background-size: cover 进行降级
过渡与动画：避免依赖不可用的 will-change，用 transform 与 opacity 实现

构建与发布建议

统一产出 ES5 包，避免差分构建导致路径复杂度提升
审计第三方依赖，必要时将 ESM 包加入转译白名单
SourceMap 保持可调试，生产环境按需关闭或改为外链
静态资源与字体格式提供 woff、ttf 双份，避免老环境渲染问题

运行时防御与降级

特性检测决定策略

if (!window.Promise) {
// 加载轻量垫片或关闭依赖该能力的分支
}
关键交互的降级路径明确，如文件上传改为全量刷新或轮询进度
错误兜底与重试，保障老环境下的容错体验

手动回归清单

页面首屏加载无报错，控制台干净
路由与基本交互（点击、表单、滚动）可用
弹层、抽屉、滚动锁定不穿透
列表与栅格布局不破版，极端数据下无溢出
上传、下载、预览链路可用
深色/浅色模式在 IE11 下保持可读性

总结

IE11 的兼容关键在于构建期的系统性配置与运行期的必要垫片，再辅以清晰的视觉与交互降级策略。通过 Babel、PostCSS 与特性检测配合，绝大多数 ES6 与 CSS 新特性都能以可接受的姿态在低版本浏览器中运行，帮助团队在历史包袱与现代体验之间达成平衡。

构建工具适配

Vite：启用核心降级插件

import legacy from '@vitejs/plugin-legacy'
export default {
plugins: [legacy({ targets: ['ie >= 11'], modernPolyfills: true })]
}
Rollup：产出 ES5 UMD 或 IIFE 以确保旧环境可执行

export default {
output: { format: 'iife' }
}
Babel 插件组合建议：@babel/preset-env 搭配 @babel/plugin-transform-runtime，减少重复辅助代码体积

module.exports = {
presets: [['@babel/preset-env', { targets: { ie: '11' }, useBuiltIns: 'usage', corejs: 3 }]],
plugins: [['@babel/plugin-transform-runtime', { corejs: false }]]
}

Polyfill 策略细化

入口统一加载少量关键能力

import 'core-js/stable'
import 'regenerator-runtime/runtime'
其余由 useBuiltIns: 'usage' 按需注入，避免过度膨胀
对于体积敏感的页面，采用能力检测后再按需动态加载轻量垫片

if (!('closest' in Element.prototype)) { await import('element-closest') }

事件与 DOM 兼容清单

Passive 事件：IE11 不支持 passive: true，统一使用普通监听或在新浏览器分支下条件开启
CustomEvent：需要垫片

(function () {
if (typeof window.CustomEvent === 'function') return
function CustomEvent(event, params) {
params = params || { bubbles: false, cancelable: false, detail: undefined }
var evt = document.createEvent('CustomEvent')
evt.initCustomEvent(event, params.bubbles, params.cancelable, params.detail)
return evt
}
CustomEvent.prototype = window.Event.prototype
window.CustomEvent = CustomEvent
})()
Element.closest 与 matches：按需引入垫片或使用手动向上遍历
classList 在 SVG 上行为不一致，尽量用属性读写而非依赖 classList
NodeList 与 HTMLCollection 不具备某些数组方法，转换为数组后再操作

var nodes = Array.prototype.slice.call(document.querySelectorAll('.item'))

国际化与日期数字格式

Intl 在 IE11 可能缺失或实现不完整，按需加载 intl 与对应 locale 数据

import 'intl'
import 'intl/locale-data/jsonp/zh'
数字与日期格式化统一通过 Intl.NumberFormat 与 Intl.DateTimeFormat，避免自实现出现地区差异

网络与数据交互

Fetch 替代：使用 whatwg-fetch 或统一采用 axios
XHR 进度事件在 IE11 表现稳定，但需避免对 responseType = 'json' 的依赖，改为文本后手动解析

var xhr = new XMLHttpRequest()
xhr.open('GET', url)
xhr.responseType = 'text'
xhr.onload = function () { var data = JSON.parse(xhr.responseText) }
xhr.send()
CORS：确保服务端返回合规的跨域响应头，避免使用不被 IE11 完整支持的复杂凭证模式

图片与媒体降级

picture 与 srcset：在旧环境用单一 img 源或引入 picturefill
WebP：提供 JPEG/PNG 回退源，服务端按 UA 或 Accept 协商
object-fit：改用包裹元素加 background-size: cover 实现

测试与调试

本地调试：使用 Edge 的 IE 模式或远程服务进行真机验证
自动化测试：Cypress 不支持 IE11，采用 Karma 搭配 karma-ie-launcher 和 Jasmine

module.exports = function (config) {
config.set({
frameworks: ['jasmine'],
browsers: ['IE'],
files: ['dist/bundle.js', 'test/**/*.spec.js']
})
}
云平台：接入 BrowserStack 或 Sauce Labs 做回归

性能与体积控制

避免在旧环境加载完全等同现代环境的重型垫片，保持按需
动态导入在 IE11 不可用，构建期改为静态分包并在路由层按条件加载
使用 @babel/plugin-transform-runtime 减少 helper 重复
监控包体积与首屏脚本执行时间，必要时禁用非核心特性

更完整的 Grid 映射示例

复制代码

.grid { display: -ms-grid; -ms-grid-columns: 1fr 1fr 1fr; -ms-grid-rows: auto auto }
.grid { display: grid; grid-template-columns: repeat(3, 1fr); grid-template-rows: repeat(2, auto) }
.a { -ms-grid-column: 1; -ms-grid-row: 1 }
.b { -ms-grid-column: 2; -ms-grid-row: 1 }
.c { -ms-grid-column: 3; -ms-grid-row: 1 }
.d { -ms-grid-column: 1; -ms-grid-row: 2 }
.e { -ms-grid-column: 2; -ms-grid-row: 2 }
.f { -ms-grid-column: 3; -ms-grid-row: 2 }

复杂布局优先使用 Flex 作为默认方案，Grid 作增强分支

常见错误速查

SCRIPT1002 Syntax error：有 ES6 语法未被转译，检查 Babel 作用范围与依赖白名单
SCRIPT438 Object doesn't support property or method：缺少 API 垫片，确认 core-js 注入
Promise 未定义：入口未加载核心垫片或被树摇优化移除
获取元素集合后调用数组方法失败：集合需先转换为数组
CSS 布局破版：确认前缀与降级策略是否同时生效，避免相互覆盖

迁移执行清单

明确兼容范围与验收标准
补充 .browserslistrc 并统一构建配置
引入核心垫片与按需策略
审计并转译第三方依赖
建立视觉与交互的降级样式
完成关键路径的 IE11 真机或云端回归
接入体积与性能监控，持续优化