浏览器 API 兼容性解决方案

解决前端项目在不同浏览器环境下的 API 兼容性问题，主要包括 ES6+ 语法转换和浏览器特定 API 的 polyfill 实现。

概念理解

Polyfill：用于实现浏览器原生不支持的功能的代码片段。通过检测浏览器是否支持某个 API，如果不支持则提供替代实现。

Babel：JavaScript 编译器，用于将 ES6+ 代码转换为向后兼容的 JavaScript 版本，确保代码能在旧版浏览器中运行。

Browserslist：用于指定项目需要兼容的浏览器版本范围。通过查询 Can I Use 数据库，为 Babel、Autoprefixer、ESLint 等工具提供统一的浏览器兼容性配置。

core-js：提供 ES 标准功能的 polyfill 库，包含 Promise、Array.from、Object.assign 等 API 的实现。

Autoprefixer：PostCSS 插件，根据 Browserslist 配置自动为 CSS 属性添加浏览器厂商前缀（如 -webkit-、-moz-）。

ES6+ Polyfill 方案

通过 Babel + Browserslist + Autoprefixer 的组合方案，实现 ES6+ 语法和 API 的兼容性处理。

工作原理

Browserslist 配置：指定需要兼容的浏览器版本范围，工具会查询 Can I Use 数据库获取兼容性信息。
Babel 语法转换：将 ES6+ 语法转换为 ES5 语法（如箭头函数转换为普通函数、解构赋值转换为普通赋值）。
API Polyfill：通过 @babel/preset-env 配合 core-js 实现 API 补全，按需加载目标浏览器缺失的 API。
CSS 前缀处理：Autoprefixer 根据 Browserslist 配置自动添加 CSS 厂商前缀。

Browserslist 配置

在项目根目录创建 .browserslistrc 文件，配置需要兼容的浏览器版本：

# .browserslistrc
last 2 versions          # 支持每个浏览器的最后 2 个版本
iOS >= 10                # iOS 10 及以上版本
Android >= 8             # Android 8 及以上版本
not dead                 # 排除已停止维护的浏览器
not IE 11                # 排除 IE 11（如需支持 IE 11，移除此行）

配置说明：

last 2 versions：支持每个浏览器的最后 2 个版本。
iOS >= 10：iOS Safari 10 及以上版本。
Android >= 8：Android 8 及以上版本。
not dead：排除已停止维护的浏览器（如 IE 10 及以下）。
not IE 11：排除 IE 11（如需支持 IE 11，需移除此行并配置相关插件）。

Babel 配置

在 babel.config.js 中配置 @babel/preset-env：

// babel.config.js
{
  "presets": [
    [
      "@babel/preset-env",
      {
        // "usage"：自动为每个文件按需引入 core-js 包下的 API polyfill
        // "entry"：入口点手动引入 core-js 的包/子包，会自动解析并引入当前包下的完整模块
        // false：不自动为每个文件添加 polyfill，也不要将 import "core-js" 转换为单独的 polyfill
        "useBuiltIns": "usage",  // 按需引入 polyfill（只加载目标浏览器缺失的 API）
        "corejs": 3,             // 指定 polyfill 库为 core-js@3
        "modules": false         // 关闭模块转换（交给 Webpack/Rollup 处理，避免冲突）
      }
    ]
  ]
}

参数说明：

useBuiltIns：
- "usage"：按需引入，自动检测代码中使用的 API，只引入需要的 polyfill（推荐）。
- "entry"：入口引入，需要在入口文件手动引入 import 'core-js'，Babel 会根据配置替换为需要的 polyfill。
- false：不自动引入 polyfill。
corejs：指定使用的 core-js 版本（推荐使用 3）。
modules：是否转换 ES6 模块语法，false 表示不转换（由打包工具处理）。

Webpack 配置

在 webpack.config.js 中配置 babel-loader：

// webpack.config.js
module.exports = {
  module: {
    rules: [
      {
        test: /\.m?js$/,          // 匹配 JS/JS 模块文件
        exclude: /node_modules/,  // 排除 node_modules（第三方库已处理兼容）
        use: 'babel-loader'       // 用 babel-loader 处理
      }
    ]
  }
};

配置说明：

test：匹配需要处理的文件类型（.js 和 .mjs）。
exclude：排除 node_modules 目录，因为第三方库通常已经处理了兼容性。
use：使用 babel-loader 处理匹配的文件。

注意事项

避免重复引入 polyfill：

使用 useBuiltIns: "usage" 时，不要手动引入 import 'core-js'，会导致 polyfill 重复，增大包体积。
若第三方库已引入部分 polyfill（如 lodash），core-js v3 会自动去重，无需额外处理。

IE 11 兼容：

移除 .browserslistrc 中的 not IE 11。
Class 语法需开启 @babel/plugin-transform-classes 插件。
避免使用 BigInt、Symbol 等无法兼容的特性。

浏览器特定 API 兼容方案

对于浏览器特定的 API（如 Blob.slice、requestAnimationFrame），可以通过全局垫片或自定义 Babel 插件实现兼容。

全局垫片方案

通过编写垫片文件，在入口处提前引入，适用于解决项目中未引入浏览器兼容 API 的代码场景。

实现示例：

// shims/blob-slice.js
// 检测 Blob 是否存在，且不支持标准 slice 方法
if (window.Blob && !Blob.prototype.slice) {
  // 优先使用 mozSlice（Firefox 私有），其次 webkitSlice（Chrome/Safari 私有）
  Blob.prototype.slice = Blob.prototype.mozSlice || Blob.prototype.webkitSlice;
}

// shims/raf.js
// requestAnimationFrame 兼容处理
if (!window.requestAnimationFrame) {
  // 优先使用 webkitRequestAnimationFrame（Chrome/Safari），其次 mozRequestAnimationFrame（Firefox）
  // 最低降级：用 setTimeout 模拟（16ms 约等于 60fps）
  window.requestAnimationFrame = window.webkitRequestAnimationFrame || 
                                  window.mozRequestAnimationFrame || 
                                  function (callback) {
                                    return setTimeout(callback, 16);
                                  };
}

// 入口文件：先加载垫片，再加载业务代码
// main.js
import './shims/blob-slice.js';
import './shims/raf.js';
import './your-business-code.js'; // 你的业务代码

使用场景：

项目中使用了浏览器特定的 API，但未引入对应的 polyfill。
需要统一处理多个浏览器特定 API 的兼容性。

自定义 Babel 插件方案

如果代码中引入了过多的浏览器兼容性 API，同时又需要兼容其他浏览器，可以在不修改代码的情况下，配合全局垫片和自定义 Babel 插件实现。

注意：这样可能存在代码编写混乱、不符合规范的场景，所以比较推荐于旧项目使用。新项目还是直接使用全局垫片解决，统一编写方案。

实现示例：

// src/babel-plugins/replace-moz-slice.js
// 自定义 Babel 插件：将 mozSlice/webkitSlice 替换为标准 slice
module.exports = function ({ types: t }) {
  return {
    visitor: {
      // 匹配「对象.属性」的表达式（如 blob.mozSlice）
      MemberExpression(path) {
        const propertyName = path.node.property.name;
        // 匹配 mozSlice 或 webkitSlice，替换为标准 slice
        if (propertyName === 'mozSlice' || propertyName === 'webkitSlice') {
          path.node.property = t.identifier('slice'); // 替换属性名为 slice
        }
      }
    }
  };
};

// babel.config.js 中引入自定义插件
{
  "plugins": [
    "./src/babel-plugins/replace-moz-slice.js" // 引入自定义插件
  ],
  "presets": [
    [
      "@babel/preset-env",
      {
        "useBuiltIns": "usage",
        "corejs": 3,
        "modules": false
      }
    ]
  ]
}

工作原理：

AST 遍历：Babel 插件通过访问者模式遍历代码的抽象语法树（AST）。
节点匹配：匹配 MemberExpression 节点（对象属性访问表达式）。
节点替换：将 mozSlice 或 webkitSlice 替换为标准的 slice。

使用场景：

旧项目中存在大量使用浏览器特定 API 的代码。
需要在不修改源代码的情况下实现兼容性处理。

总结

ES6+ 语法和 API 兼容：通过 Babel + Browserslist + core-js 实现，使用 useBuiltIns: "usage" 按需引入 polyfill。
浏览器特定 API 兼容：通过全局垫片或自定义 Babel 插件实现，推荐新项目使用全局垫片方案。
Browserslist 配置会被 Babel、Autoprefixer、ESLint 等工具共享，确保兼容性处理的一致性。

参考内容

@babel/preset-env · Babel 中文网

浏览器 API 兼容性解决方案