Legacy 构建与兼容性指南（Vite / Webpack）

目的

本文档说明如何使用 legacy 构建以增强旧浏览器（例如较低版本 iOS / Safari）的兼容性，以及何时应该在源码层修复问题。

重要提醒

部分问题（尤其是正则引擎级语法，如 lookbehind (?<!...)）无法通过 polyfill 修复。legacy 构建可以转换语法和注入 API polyfill，但不能向旧的 JS 运行时“增加”正则引擎特性。如果遇到这类问题，必须在源码层重写或延迟构造并运行时检测/回退。详见 ios-regex-compat 文档。

Vite（推荐）

安装：

bash

pnpm add -D @vitejs/plugin-legacy

示例配置（vite.config.ts）：

import legacy from '@vitejs/plugin-legacy'
import { defineConfig } from 'vite'

export default defineConfig({
  plugins: [
    legacy({
      targets: ['defaults', 'iOS >= 11'],
      additionalLegacyPolyfills: ['regenerator-runtime/runtime'],
      renderLegacyChunks: true,
    })
  ]
})

注意：

targets 决定哪些语法/Polyfill 需要应用。根据需要支持的最低版本设置。
additionalLegacyPolyfills 可以把运行时库注入到 legacy bundle。
renderLegacyChunks 生成按需加载的 legacy chunk，并配合 type="module" / nomodule 差异化加载。
但 plugin-legacy 无法改写正则 lookbehind 等引擎级语法；此类问题仍需在源码层处理。

Webpack

常见做法是用 Babel 做两套构建（modern + legacy），通过 type="module" / nomodule 差异化服务。示例依赖与 babel.config.js 请参考英文文档上半部分。

Polyfills

使用 core-js（v3）和 Babel 的 useBuiltIns: 'usage'，并仅在 legacy 构建中注入需要的 polyfill。

正则语法特殊说明

引擎级正则语法必须在源码层处理：改写或运行时延迟构造并做 feature-detect。

测试与 CI

在 CI 中运行 modern + legacy 构建，并在旧设备/模拟器上做 smoke tests。可加入静态检查阻止新提交引入高级正则写法。

快速检查（本地）

bash

pnpm dlx rg "\\(\\?<!|\\(\\?<=|\\\\p\\{" --glob "**/*.{js,ts,vue,jsx,tsx,mjs,cjs}" -n

总结

优先在源码层修复不兼容的正则语法；使用 legacy 构建来覆盖语法与 API 差异，并在 CI/QA 中验证旧设备表现。

Legacy 构建与兼容性指南（Vite / Webpack） ​

Legacy 构建与兼容性指南（Vite / Webpack）