deerflow-code/frontend-web/docs/firefox52-dependency-compatibility.md

Firefox 52 第三方依赖兼容清单

本文记录 fix/firefox52-compat 分支中会影响 Firefox 52 的依赖、处理方式和回归入口。版本以 2026-10-09 的 pnpm-lock.yaml 实际解析结果为准；升级表内依赖后必须重新执行文末检查。

分级

等级	含义	当前处理
A	原生可运行，或由项目统一 SWC 转换即可运行	使用 Rspack 的 Firefox 52 单目标转换
B	语法可转换，但缺少浏览器 API	在 src/core/compat/firefox52.ts 做能力检测后安装 polyfill
C	依赖源码含 async iterator 等需要额外 Babel 转换的语法	精确 allowlist 后交给专用 loader
D	含 BigInt、危险正则或平台实现差异，普通转译不能解决	固定版本并做带断言的精确源码替换或替代实现
E	Firefox 52 网络层不提供现代流式 fetch 等能力	提供保持业务协议的运行时回退

已验证依赖

依赖/能力	实际版本	等级	处理与验证
React / React DOM	18.3.1	A	兼容分支从 React 19 降为 18.3；所有页面统一使用这一运行时。118 条路由矩阵用于发现 Provider/Hook 运行时问题。
React Router DOM	7.18.4	D	source-compat-loader.cjs 处理动态路由模块加载差异；Hash 路由、重定向、刷新、公开页和 iframe 均进入完整路由冒烟。
Tailwind CSS	3.4.19	A	采用 Tailwind 3 生成静态 utility；PostCSS 展平 @layer，转换 :where()、暗色后代规则和 CSS 变量透明色。
Rspack	2.2.8	A	target: ["web", "es5"]，SWC/Lightning CSS 的目标均为 Firefox 52；使用普通 script 与 Rspack chunk loader。
@langchain/core	1.2.17	C	LangChain 包进入 async-iteration loader；真实问答验证 thread 创建、XHR 流、导航和最终回复。
@langchain/langgraph-sdk	1.12.3	C	对 async generator 和普通 async 方法中的 for await 做两阶段 Babel 转换；回归测试防止退化为同步 Symbol.iterator。
LangSmith	0.10.8	D	进入源码兼容 loader，替换 Firefox 52 不支持的 BigInt/哈希实现路径；产物静态扫描兜底。
p-queue	6.6.2 / 9.3.3	D	精确处理 BigInt 并发计数；loader 找不到预期源码时直接让构建失败，避免静默输出危险代码。
React Flow (@xyflow/react)	12.12.0	D	仅把内部渲染序号的 BigInt(0) 和递增改为 Number；流程图相关路由已在 Firefox 52 中加载。
Shiki	3.15.0	D	重型模块按需分块；其 Oniguruma JS 引擎进入下面的正则兼容处理。
Oniguruma parser	0.12.2	D	移除 Firefox 52 不支持且不改变当前匹配语义的正则 flag；代码高亮页面与产物语法检查共同验证。
Mermaid	11.17.2	C	由 Rspack/SWC 转换并按需加载；Markdown/研究/会商入口纳入路由矩阵。
Zod	3.24.x（直接依赖）	D	依赖源码进入兼容 loader，处理 BigInt 上下界；扫描最终 chunks 是否残留危险语法。
MapLibre GL	4.7.1	D	固定在可转换版本；保持 Leaflet/静态信息回退，避免升级后引入 Firefox 52 无法执行的 Worker/语法。
CodeMirror / Tiptap / KaTeX / Marked	锁文件版本	A/C	由 SWC 统一转换并路由级加载；Markdown 编辑器、预览和 Word 导出均有真实浏览器冒烟。
Radix UI / TDesign / cmdk	锁文件版本	A/B	Pointer Events、ResizeObserver、Portal 点击和滚动锁由兼容入口及分层 CSS 处理；菜单、选择器、弹窗、Tabs 有点击测试。
docx / file-saver	9.5.1 / 2.0.5	B	正式 Word 由后端生成；Firefox 52 冒烟验证非空 DOCX Blob、MIME 和 .docx 下载文件名。
xlsx 解压	fflate 0.8.3	D	浏览器端解压路径改为 fflate，避开原实现的现代能力依赖。

浏览器 API 与平台回退

src/core/compat/firefox52.ts 在应用入口最先加载，按能力补充 AbortController、AbortSignal、Observers、Web Streams、Pointer Events、requestSubmit、scrollIntoView、Clipboard、Blob/File、UUID 等能力。所有补丁先检查原生实现，现代浏览器不会被无条件覆盖。

Firefox 52 的 fetch() 没有可供业务消费的流式 Response.body。src/core/compat/firefox52-fetch.ts 用 XMLHttpRequest.onprogress 构造兼容的增量响应，保留请求头、鉴权、取消、错误状态和 SSE/NDJSON 分片语义。该路径属于 E 级平台回退，不能删除后只依赖 Web Streams polyfill。

升级规则

1. 修改表内版本后先运行 pnpm test:firefox52-build。精确源码片段不匹配会直接失败，此时需重新审计依赖实现，不能放宽成无条件替换。
2. 执行 pnpm build:firefox52 && pnpm check:firefox52，确认最终 HTML、CSS、JS 与所有动态 chunks 都能被 Firefox 52 解析。
3. 启动 Firefox 52 后执行 pnpm smoke:firefox52:themes、pnpm smoke:firefox52:live 和 pnpm smoke:firefox52:full。
4. LangChain、LangGraph、LangSmith、p-queue、React Router、XYFlow、Oniguruma、Shiki、Mermaid、MapLibre 任一升级，都必须重新跑真实流式问答和相关懒加载路由，不能只看构建成功。

当前限制

• WebGL 的最终可用性还受显卡、远程桌面和驱动影响；无 WebGL 环境应走现有的二维或文本信息回退。
• 1366×768、1920×1080、2560×1440 的精确视觉截图需要对应大小的真实显示环境。当前自动化会读取真实 DOM 尺寸和样式，但不会伪造操作系统无法提供的物理视口。
• 创建、删除、发布、回滚等会修改业务数据的管理操作不在自动点击矩阵中；这些页面会验证加载、可见 Tabs 与未捕获异常，数据写入流程由专门测试数据验收。