feat: add legacy builds documentation and improve regex compatibility for older iOS

Simon-He95 · Simon-He95 · commit 425ce4419234 · 2025-11-25T23:31:16.000+08:00
close: #162
diff --git a/docs/.vitepress/config.ts b/docs/.vitepress/config.ts
@@ -71,6 +71,7 @@ export default defineConfig({
             { text: 'Math', link: '/guide/math' },
             { text: 'Mermaid', link: '/guide/mermaid' },
             { text: 'Tailwind', link: '/guide/tailwind' },
+            { text: 'Legacy builds & iOS regex compatibility', link: '/guide/legacy-builds' },
             { text: 'Thanks', link: '/guide/thanks' },
           ],
         },
@@ -124,6 +125,7 @@ export default defineConfig({
             { text: 'Math', link: '/zh/guide/math' },
             { text: 'Mermaid', link: '/zh/guide/mermaid' },
             { text: 'Tailwind', link: '/zh/guide/tailwind' },
+            { text: 'Legacy 构建与 iOS 正则兼容', link: '/zh/guide/legacy-builds' },
             { text: '致谢', link: '/zh/guide/thanks' },
             {
               text: '研究与调查',
@@ -163,6 +165,7 @@ export default defineConfig({
             { text: 'Math', link: '/guide/math' },
             { text: 'Mermaid', link: '/guide/mermaid' },
             { text: 'Tailwind', link: '/guide/tailwind' },
+            { text: 'Legacy builds & iOS regex compatibility', link: '/guide/legacy-builds' },
             { text: 'Thanks', link: '/guide/thanks' },
           ],
         },
diff --git a/docs/LEGACY-BUILDS.md b/docs/LEGACY-BUILDS.md
@@ -0,0 +1,159 @@
+# Legacy 构建与兼容性指南（Vite 与 Webpack）
+
+目的
+- 当你遇到旧浏览器（例如低版本 iOS / Safari）导致页面白屏或运行时报错的兼容性问题时，应考虑两类方案：
+  1. 在源码层修复（首选，必要时必须做的，比如 RegExp 语法不可能被 polyfill）
+  2. 在构建/部署层使用 legacy 构建（为旧浏览器生成降级 bundle + polyfills）
+
+重要提醒（核心）
+- 一些问题（例如使用正则 lookbehind `(?<!...)`）是 JS 引擎级语法问题：无法用 polyfill 在旧引擎中“添加”正则语法支持。换言之，legacy 构建能转换语法和注入 API polyfill，但不能把运行时未实现的正则语法自动转换为等价旧写法。遇到这类问题，应在源码层重写或在运行时做特性检测并 fallback（参见 `docs/IOS-regex-compat.md`）。
+
+下面文档提供：
+- Vite 的 `@vitejs/plugin-legacy` 用法与 caveats
+- Webpack 下实现 modern/legacy 差异化构建的常见模式
+- polyfills 管理（`core-js` / `regenerator-runtime` / 浏览器目标）
+- 测试与 CI 建议
+
+1) Vite（推荐用于 Vite 项目）
+
+- 安装（项目根）：
+
+```bash
+pnpm add -D @vitejs/plugin-legacy
+```
+
+- 最简单的配置（vite.config.ts）
+
+```ts
+import legacy from '@vitejs/plugin-legacy'
+import { defineConfig } from 'vite'
+
+export default defineConfig({
+  plugins: [
+    legacy({
+      targets: ['defaults', 'iOS >= 11'],
+      additionalLegacyPolyfills: ['regenerator-runtime/runtime'],
+      // modern polyfilled bundle + legacy (nomodule) bundle -> differential serving
+      renderLegacyChunks: true,
+    })
+  ]
+})
+```
+
+- 解释与建议：
+  - `targets` 使用浏览器目标来决定哪些语法/transform 需要降级；根据你需要支持的最低版本设置（例如 `iOS >= 11`）。
+  - `additionalLegacyPolyfills` 可以把某些运行时库插入 legacy bundle；但大多数 API polyfill（例如 `Promise` / `fetch`）应通过 `core-js` 或手动引入更精细地控制。
+  - `renderLegacyChunks: true` 会生成兼容旧浏览器的 chunk（按需 polyfill 注入），并配合 `<script type="module">` / `<script nomodule>` 差异化加载。
+  - plugin-legacy 使用 Babel 来转换语法，但**无法**把正则 lookbehind 之类的引擎级语法“改写”为等价旧写法：如果源码里有不支持的正则语法，仍可能在打包时或运行时报错（取决于是否把该正则放到运行时构造）。因此仍要在源码层修复正则语法。
+
+- 使用建议流程：
+  1. 尝试用 runtime feature detection（例如 `new RegExp('(?<!a)b')`）判断是否需要改写/延迟构造正则字面量。
+  2. 为支持低版本平台保留 legacy 构建（plugin-legacy）以覆盖大多数语法 / API 差异。
+  3. 在 QA/CI 上用旧 iOS Safari（或 BrowserStack）验证构建产物。查看是否有 `SyntaxError: Invalid regular expression` 类型错误（若有，说明源码中有不兼容的正则字面量仍需改写）。
+
+2) Webpack（适用于基于 Webpack 的项目）
+
+Webpack 没有像 Vite 那样开箱即用的单一插件来生成 differential bundles，但常见方案是：使用 Babel 对代码做两套构建（modern + legacy），并用 `type="module"` / `nomodule` 或不同 HTML 输出来差异化服务。
+
+- 关键依赖
+
+```bash
+pnpm add -D @babel/core babel-loader @babel/preset-env core-js regenerator-runtime webpack webpack-cli
+```
+
+- 简单思路（多配置/多构建）
+  - 配置 A（modern）：目标现代浏览器（browserslist 可设置），输出 `module` bundle
+  - 配置 B（legacy）：目标旧浏览器，开启更激进的 `@babel/preset-env` 转换与 `useBuiltIns: 'usage'`，并注入 `core-js` polyfills
+
+示例 `babel.config.js`（用于 legacy 构建）
+
+```js
+module.exports = function (api) {
+  const isLegacy = api.env('legacy')
+  return {
+    presets: [
+      [
+        '@babel/preset-env',
+        {
+          targets: isLegacy ? { ie: '11', ios: '10' } : { esmodules: true },
+          useBuiltIns: isLegacy ? 'usage' : false,
+          corejs: isLegacy ? { version: 3, proposals: false } : undefined,
+        },
+      ],
+    ],
+  }
+}
+```
+
+然后在 package.json 中定义两个构建命令（分别以不同的 NODE_ENV/env 来调用 babel）：
+
+```json
+{
+  "scripts": {
+    "build:modern": "cross-env BABEL_ENV=modern webpack --config webpack.modern.config.js",
+    "build:legacy": "cross-env BABEL_ENV=legacy webpack --config webpack.legacy.config.js",
+    "build": "pnpm run build:modern && pnpm run build:legacy"
+  }
+}
+```
+
+- HTML 部署时使用 `type="module"` / `nomodule`：
+
+```html
+<script type="module" src="/assets/app.modern.js"></script>
+<script nomodule src="/assets/app.legacy.js"></script>
+```
+
+- 注意事项：
+  - 两套构建会增加构建复杂度与 CI 时间；但可以确保对旧浏览器的兼容性控制更粒度。
+  - 同样强调：如果源码中包含引擎级不支持的正则字面量（例如 lookbehind），在构建阶段仍可能失败或在旧浏览器上报错 —— 这些必须在源码层修复或用运行时延迟构造。
+
+3) polyfills 管理建议
+- 使用 `core-js`（v3）做标准 API polyfill，结合 Babel 的 `useBuiltIns: 'usage'` 自动注入，或手动在入口文件按需 `import 'core-js/stable'`。
+- 对于 async/await：`regenerator-runtime/runtime`。
+- 注意不要把不必要的 polyfill注入到 modern bundle；使用 differential serving（或 plugin-legacy）确保最小现代 bundle。
+
+4) 正则（RegExp）与引擎级语法的特殊说明
+- 正则语法（例如 lookbehind）是 JS 引擎实现的语言特性，无法用 runtime polyfill 修复。解决办法：
+  - 在源码中改写为兼容写法（例如把 `(?<!a)b` 改为 `(^|[^a])b` 或使用字符串检查回调），或
+  - 把潜在会抛错的正则延迟为运行时构造（`new RegExp(...)`）并在运行时做 feature-detection（参考 `docs/IOS-regex-compat.md`），以避免模块加载解析时报错。
+
+5) 测试与 CI / 预提交检查
+- 在 CI 中加入：
+  - `pnpm run build`（确保 modern+legacy 构建在 CI 执行无异常）
+  - 旧版浏览器 smoke tests（可选）：用 BrowserStack / SauceLabs 在 iOS 16.2 / Safari 等上做速测，或在 Xcode Simulator 上跑关键页面。
+  - 静态检测脚本：阻止新提交引入诸如 `(?<!` / `(?<=` 的字面量正则（示例脚本见下）。把脚本加入 `package.json` 并在 CI/预提交钩子里运行。
+
+示例检查脚本（package.json -> scripts）
+
+```json
+{
+  "scripts": {
+    "check:regex-advanced": "rg --hidden --glob '!node_modules' --glob '!dist' -n --glob '**/*.{js,ts,vue,jsx,tsx,mjs,cjs}' '\\(\\?<!|\\(\\?<=|\\(\\?<[^=]|\\\\p\\{' || true"
+  }
+}
+```
+
+6) 快速排错清单（当你看到旧设备白屏或控制台有错误时）
+- 打开控制台，查找 `SyntaxError: Invalid regular expression` 或语法错误；如果是 RegExp 报错，优先检查源码是否含 lookbehind 等高级特性。
+- 用 `rg '\\(\\?<!|\\(\\?<=|\\\\p\\{'` 在源码中搜索（排除缓存文件与 node_modules）。
+- 若查明是正则语法导致：在源码中改写或延迟构造；不要仅依赖 legacy 构建来修复此类问题。
+- 若是其它语法/API：确保 legacy 构建或 Babel preset-env 的 targets 包含你需要支持的版本，并把 polyfill 策略设置为 `usage`（或按需引入）。
+
+7) 总结要点（简短）
+- legacy 构建（Vite plugin-legacy / Webpack + Babel 两套构建）能解决大量语法与 API 的兼容问题，但不能修复 JS 引擎本身不支持的正则语法（如 lookbehind）。遇到这类问题，必须在源码层改写或使用运行时检测与 fallback。
+- 推荐流程：优先源码兼容 -> 在构建中添加 legacy 支持 -> 在 CI/QA 上验证旧设备的真实表现 -> 在项目中加入静态检查以防回归。
+
+附录：参考命令
+
+```bash
+# Vite 本地打包 (含 legacy)
+pnpm build
+
+# Webpack 两套构建 (示例)
+pnpm run build:modern
+pnpm run build:legacy
+
+# 静态检查（本地快速跑）
+pnpm dlx rg "\\(\\?<!|\\(\\?<=|\\\\p\\{" --glob "**/*.{js,ts,vue,jsx,tsx,mjs,cjs}" -n
+```
diff --git a/docs/guide/legacy-builds.md b/docs/guide/legacy-builds.md
@@ -0,0 +1,80 @@
+# Legacy build & compatibility guide (Vite / Webpack)
+
+Purpose
+- This document explains how to use legacy builds to improve compatibility with older browsers (for example older iOS / Safari) and when you should instead fix issues in source code.
+
+Key reminder
+- Some problems (notably RegExp engine-level syntax like lookbehind `(?<!...)`) cannot be fixed by polyfills. Legacy builds transform syntax and inject API polyfills but cannot add RegExp engine features to an older JS runtime. If you encounter such issues, you must either rewrite the code or delay construction/runtime-detect and fallback. See `ios-regex-compat.md` for details.
+
+What this page covers
+- Vite: `@vitejs/plugin-legacy` usage and caveats
+- Webpack: common two-build (modern + legacy) approaches
+- Managing polyfills (`core-js`, `regenerator-runtime`) and targets
+- Testing, CI and quick debug checklist
+
+Vite (recommended if your project uses Vite)
+
+Install:
+
+```bash
+pnpm add -D @vitejs/plugin-legacy
+```
+
+Example `vite.config.ts`:
+
+```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,
+    })
+  ]
+})
+```
+
+Notes
+- `targets` controls which transforms/polyfills are applied. Set to your minimum supported browsers.
+- `additionalLegacyPolyfills` injects runtime libraries into the legacy bundle.
+- `renderLegacyChunks` enables differential chunks served via `type="module"` / `nomodule`.
+- Important: plugin-legacy cannot rewrite engine-level RegExp syntax (lookbehind). Keep incompatible regex out of literal module scope or rewrite them.
+
+Webpack
+
+Webpack does not provide a single plugin equivalent to Vite's plugin-legacy. Common approach: build two bundles with Babel (modern + legacy) and serve them with `type="module"` / `nomodule`.
+
+Key deps:
+
+```bash
+pnpm add -D @babel/core babel-loader @babel/preset-env core-js regenerator-runtime webpack webpack-cli
+```
+
+Example approach
+- Create a `babel.config.js` that supports `BABEL_ENV=legacy` to enable `useBuiltIns: 'usage'` and a legacy `targets` set. Run two webpack builds: one modern, one legacy. Serve modern bundle with `<script type="module">` and legacy with `<script nomodule>`.
+
+Polyfills
+- Use `core-js` for standard API polyfills (v3). For generators/async: `regenerator-runtime/runtime`.
+- Prefer differential serving so modern bundles stay small.
+
+RegExp and engine-level syntax
+- RegExp features such as lookbehind are implemented by the JS engine. Polyfills cannot add them. Either
+  - rewrite the regex to a compatible form, or
+  - delay regex construction (use `new RegExp(...)`) and use runtime feature-detection + fallback.
+
+Testing & CI
+- Add `pnpm run build` (modern + legacy) in CI and run smoke tests on older browsers (BrowserStack / SauceLabs or Xcode simulator).
+- Add a static check to block new lookbehind/unicode-regex features (see examples below).
+
+Quick local checks
+
+```bash
+# Static scan for advanced regex in source
+pnpm dlx rg "\\(\\?<!|\\(\\?<=|\\\\p\\{" --glob "**/*.{js,ts,vue,jsx,tsx,mjs,cjs}" -n
+```
+
+Summary
+- Legacy builds are useful for many syntax & API gaps, but they are not a replacement for fixing engine-level RegExp syntax in source. Prefer: source fix -> legacy bundle -> CI + old-device smoke tests.
diff --git a/docs/zh/guide/legacy-builds.md b/docs/zh/guide/legacy-builds.md
@@ -0,0 +1,60 @@
+# 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`）：
+
+```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 中验证旧设备表现。
diff --git a/packages/markdown-parser/src/plugins/isMathLike.ts b/packages/markdown-parser/src/plugins/isMathLike.ts
@@ -35,8 +35,10 @@ const TEX_SPECIFIC_RE = /\\(?:text|frac|left|right|times)/
 // ensuring a lone '+' isn't matched when it's part of a '++' sequence.
 // Use a RegExp constructed from a string to avoid issues escaping '/' in a
 // regex literal on some platforms/linters.
+
+// Avoid lookbehind for older iOS: use a non-capturing prefix instead
 // eslint-disable-next-line prefer-regex-literals
-const OPS_RE = new RegExp('(?<!\\+)\\+(?!\\+)|[=\\-*/^<>]|\\\\times|\\\\pm|\\\\cdot|\\\\le|\\\\ge|\\\\neq')
+const OPS_RE = new RegExp('(?:^|[^+])\\+(?!\\+)|[=\\-*/^<>]|\\\\times|\\\\pm|\\\\cdot|\\\\le|\\\\ge|\\\\neq')
 // Hyphenated multi-word (like "Quasi-Streaming") should not be treated
 // as a math operator. But single-letter-variable hyphens (e.g. "x-y") are
 // still math; so only ignore hyphens between multi-letter words.
diff --git a/packages/markdown-parser/src/plugins/math.ts b/packages/markdown-parser/src/plugins/math.ts
@@ -91,7 +91,12 @@ const SINGLE_BACKSLASH_NEWLINE_RE = /(^|[^\\])\\\r?\n/g
 const ENDING_SINGLE_BACKSLASH_RE = /(^|[^\\])\\$/g
 
 // Cache for dynamically built regexes depending on commands list
-const DEFAULT_MATH_RE = new RegExp(`${CONTROL_CHARS_CLASS}|(?<!\\\\|\\w)(${ESCAPED_KATEX_COMMANDS})\\b`, 'g')
+// Avoid lookbehind; capture possible prefix so replacements can preserve it.
+// Pattern groups:
+// 1 - control char (e.g. '\t')
+// 2 - optional prefix char (start or a non-word/non-backslash)
+// 3 - command name
+const DEFAULT_MATH_RE = new RegExp(`(${CONTROL_CHARS_CLASS})|(${ESCAPED_KATEX_COMMANDS})\\b`, 'g')
 const MATH_RE_CACHE = new Map<string, RegExp>()
 const BRACE_CMD_RE_CACHE = new Map<string, RegExp>()
 
@@ -105,7 +110,9 @@ function getMathRegex(commands: ReadonlyArray<string> | undefined) {
   if (cached)
     return cached
   const commandPattern = `(?:${arr.map(c => c.replace(/[.*+?^${}()|[\\]\\"\]/g, '\\$&')).join('|')})`
-  const re = new RegExp(`${CONTROL_CHARS_CLASS}|(?<!\\\\|\\w)(${commandPattern})\\b`, 'g')
+  // Use non-lookbehind prefix but capture the prefix so replacement can
+  // re-insert it. Groups: (control) | (prefix)(command)
+  const re = new RegExp(`(${CONTROL_CHARS_CLASS})|(${commandPattern})\\b`, 'g')
   MATH_RE_CACHE.set(key, re)
   return re
 }
@@ -159,11 +166,17 @@ export function normalizeStandaloneBackslashT(s: string, opts?: MathOptions) {
   // Build or reuse regex: match control chars or unescaped command words.
   const re = getMathRegex(useDefault ? undefined : commands)
 
-  let out = s.replace(re, (m: string, cmd?: string) => {
-    if (CONTROL_MAP[m] !== undefined)
-      return `\\${CONTROL_MAP[m]}`
-    if (cmd && commands.includes(cmd))
+  // Replace callback receives groups: (match, controlChar, cmd)
+  let out = s.replace(re, (m: string, control?: string, cmd?: string, offset?: number, str?: string) => {
+    if (control !== undefined && CONTROL_MAP[control] !== undefined)
+      return `\\${CONTROL_MAP[control]}`
+    if (cmd && commands.includes(cmd)) {
+      // Ensure we are not inside a word or escaped by a backslash
+      const prev = (str && typeof offset === 'number') ? str[offset - 1] : undefined
+      if (prev === '\\' || (prev && /\w/.test(prev)))
+        return m
       return `\\${cmd}`
+    }
     return m
   })
 
