32 KiB
Firefox 52 全功能兼容与 Rspack 高性能构建开发计划
1. 文档信息
| 项目 | 内容 |
|---|---|
| 目标分支 | fix/firefox52-compat |
| 独立工作区 | F:\react01\firefox-web |
| 前端目录 | F:\react01\firefox-web\frontend-web |
| 目标浏览器 | Firefox 52(Windows x64) |
| 技术方向 | React 18.3 + Tailwind CSS 3.4 + Rspack 2.x + 内置 SWC |
| 核心目标 | 尽可能保持现有全部功能,提高冷构建和增量构建速度,保证主要页面与主题样式 |
| 当前状态 | 兼容构建与自动回归已接通:核心交互 20/20、主题布局 12/12、完整路由 118/118,真实普通问答与智能体问答均通过 |
1.1 2026-10-09 实施进度
已完成:
- 建立 Firefox 52 专用 Rspack/SWC 单目标构建,开发服务器、快速构建、正式构建和预览命令均已接通;持久化缓存生效。当前机器实测冷生产构建 16.865 秒,首轮后的四次稳态构建中位数 1.584 秒、P95 1.641 秒。
- 运行时降级到 React 18.3;Tailwind CSS 采用
feat/tailwind-v3-legacy-chrome已验证方案降级到 3.4,保留现有主题 token 和组件类名。 - 建立统一兼容入口,补齐 Pointer Events、
requestSubmit、scrollIntoView({block:"nearest"})、Blob、UUID、Clipboard、ResizeObserver、Web Streams 等能力。 - 流式请求使用 XHR
onprogress适配 SSE/NDJSON/Range 等接口;单元测试 4/4 通过。 - 修复 Firefox 52 下的 SPA 路由白屏、
display: contents根布局失效、侧边栏分隔线颜色、首页宽度 token、欢迎标题透明、常用提示词换行、Radix 菜单无法点击、cmdk 下拉框崩溃和 Enter 无法发送。 - CSS 兼容样式拆到
src/styles/firefox52/;PostCSS 自动转换rgb(var(...) / alpha)、:where()和暗色后代选择器,并为 flex gap 提供回退。 - MapLibre 固定到 4.7.1,xlsx 解压改用 fflate;对 LangChain/LangGraph/LangSmith、Oniguruma、React Router、Zod 等依赖启用精确转换或源码兼容 loader。
- 修复 LangGraph 普通 async 方法中
for await被错误降为同步迭代的问题,并增加 loader 回归测试;修复 XYFlow 12.12 的 BigInt 渲染序号导致流程页面白屏的问题。 - 增加
check:firefox52-css、check:firefox52-js、核心交互、真实流式、主题布局和 118 条完整路由脚本,用于阻止现代 CSS/JS 语法、路由和页面交互回归。 - 建立
docs/firefox52-dependency-compatibility.md和docs/firefox52-route-compatibility.md,记录版本、补丁原因、验证入口与平台限制。
本阶段验证结果:
| 验证项 | 结果 |
|---|---|
| Firefox 52 核心页面与交互冒烟 | 20/20 通过 |
| Firefox 52 真实普通问答 | 线程创建、路由跳转、XHR 增量流与最终回复均通过 |
| Firefox 52 真实智能体问答 | 自动选择可用智能体,线程创建、XHR 增量流与最终回复均通过 |
| 主题与布局 | 6 套主题 × 全量/简洁布局,12/12 通过 |
| Word 导出 | 后端实际生成非空 DOCX,MIME 与下载文件名通过 |
| 完整路由 | 开发与生产预览均为 118/118;分别点击 71/74 个可见非破坏性 Tabs;强制刷新模式支持按过滤器分批运行 |
| 关键交互 | 设置和更多、换肤、Agent/模型选择、提示词管理、Enter 提交、项目创建、业务链条、定时任务新建、Markdown 编辑器与 Word 下载 |
| 正式产物 CSS 检查 | 通过 |
| 正式产物 Acorn ES2017 解析 | 464/464,通过 |
Firefox 52 浏览器自身 new Function 解析 |
464/464,0 错误 |
| 正式产物 JS 体积 | 25.2 MiB(464 个按需 chunk) |
| Rspack 生产构建 | 冷构建 16.865 秒;稳态中位数 1.584 秒、P95 1.641 秒 |
管理员、任务、iframe、公开页、canvas、会商和设置等静态入口已纳入完整路由矩阵。需要特定任务参数、外部系统、业务数据写入、硬件 WebGL 或精确物理分辨率的流程,仍需在对应部署环境补充人工验收,不能用静态入口通过替代。
2. 建设目标
本项目在独立兼容分支中建设 Firefox 52 专用前端构建链。现代浏览器版本继续在主开发目录使用现有 Vite 构建,兼容分支只生成 Firefox 52 单目标产物,不生成现代与旧版两套 bundle。
开发遵循以下目标:
- 功能覆盖优先:现有路由和主要业务流程都必须进入兼容验收矩阵,不能以“首页能够打开”作为完成标准。
- 构建性能优先:使用 Rspack、SWC、增量编译和持久化缓存,移除 legacy bundle 的二次 Babel/SystemJS 转换。
- 样式一致性优先:保留 Tailwind、TDesign、Radix 和自定义主题,系统处理 Firefox 52 不支持的 CSS 语法与布局能力。
- 兼容逻辑可维护:浏览器差异集中到构建配置、兼容入口、传输适配器和依赖补丁,不在业务组件中散落版本判断。
- 持续跟进主分支:兼容分支能够定期合并
master-zg的新功能,并通过自动检查发现新增的不兼容依赖和语法。
3. 完成标准
3.1 功能标准
- Firefox 52 打开登录页、首页和工作区时没有白屏。
- 首屏与路由切换没有未捕获 JavaScript 异常、语法错误和 chunk 加载错误。
- 功能矩阵中的 P0、P1 场景全部通过;P2 场景逐项验证并记录结果。
- 无法由旧浏览器实现的原生能力必须提供等价回退,页面和主流程不能直接不可用。
- 文件上传、文件下载、流式问答、Markdown、公式、代码块、流程图和 Word 导出必须作为专项验收项。
- iframe、任务深链、公开分享页面和运行时配置必须保持现有 URL 与接口行为。
3.2 性能标准
先在阶段 0 获取当前 Vite legacy 的基线,后续使用相同机器、相同源码、相同依赖和相同环境重复测试。最终门槛如下:
| 指标 | 目标 |
|---|---|
| 开发服务器首次可访问时间 | 不高于基线的 50%,期望不超过 10 秒 |
| 修改单个 TSX 后的增量构建 | P95 不超过 1.5 秒 |
| 修改全局 CSS 后的增量构建 | P95 不超过 2 秒 |
| 无缓存生产构建 | 不高于基线的 50% |
| 有缓存生产构建 | 不高于基线的 30% |
| 连续构建稳定性 | 连续 10 次无随机失败、无失效 chunk、无内存溢出 |
| 产物浏览器检查 | 不含 Firefox 52 无法解析的模块入口和已知危险语法 |
绝对时间与相对提升发生冲突时,以“功能正确、样式正确、相对基线明显提升”为判断顺序。未达到性能门槛前不移除旧构建链。
3.3 样式标准
- 全量模式、简洁模式、嵌入模式均无整体布局塌陷。
- 浅色、深色、浅蓝、浅绿、冰蓝、浅黄等现有主题逐一验证。
- 重点分辨率至少覆盖
1366×768、1920×1080、2560×1440。 - 导航栏、侧边栏、表单、表格、标签页、弹窗、下拉框、Tooltip、抽屉和浮层没有明显错位或遮挡。
- 页面不得出现因
@layer、现代颜色语法或不支持的选择器导致的整片无样式。 - 主流程截图与现代浏览器参考图保持结构、间距、颜色和层级一致;字体抗锯齿造成的细微像素差异不作为失败。
4. 当前兼容基线
兼容分支已经存在以下措施,Rspack 迁移必须先等价承接,再进行优化:
@vitejs/plugin-legacy生成 Firefox 52 的 SystemJS legacy bundle。- Mermaid legacy chunk 额外经过 Babel 转换。
- 对
p-queue、GFM autolink、Oniguruma parser、LangSmith XXHash 进行构建期源码补丁。 - 入口安装 AbortController、IntersectionObserver、ResizeObserver 和 Web Streams polyfill。
- PostCSS 展平 Tailwind
@layer。 - 自定义颜色回退和 Lightning CSS 目标转换。
- 全局样式中已经维护主题对应的 legacy 色值。
index.html在应用入口前安装AbortSignal.timeout回退。
当前方案的主要问题:
- Vite 开发服务器依赖现代 ESM,Firefox 52 无法直接用于日常开发调试。
- legacy 构建对最终 chunks 再执行 Babel 和 SystemJS 转换,模块量越大耗时越明显。
- 依赖源码在构建过程中做字符串替换,缓存命中率、升级稳定性和错误定位都较差。
- Web Streams polyfill只能补充 JavaScript API,不能自动让 Firefox 52 的
fetch响应具备网络流式读取能力。 - CSS 已有回退主要围绕旧版 Chrome 建设,还需要按 Firefox 52 实际渲染能力重新审计。
5. 总体技术方案
5.1 构建链
Firefox 52 专用构建使用以下组件:
@rspack/core@rspack/cli@rspack/dev-serverbuiltin:swc-loader- Rspack SWC JavaScript minimizer
- Rspack Lightning CSS minimizer或现有 PostCSS + Lightning CSS 流程
- HTML 生成插件、资源复制插件和 React Refresh 集成(确认 Firefox 52 可运行后启用)
构建目标分成两层:
- Rspack runtime 目标指定 Firefox 52,保证 chunk loader、bootstrap 和 HMR runtime 不输出危险语法。
- SWC
env.targets指定 Firefox 52,负责 TS、TSX、JSX 和业务 JavaScript 的语法降级及 core-js 注入。
生产构建仅输出一套 Firefox 52 产物,使用普通 script/JSONP chunk loading,不保留 Vite legacy 的 SystemJS 双阶段处理。
5.2 配置与资源保持
迁移时保持以下外部行为:
runtime-config.js继续在应用 bundle 之前加载。- 保持现有
VITE_*配置键,不要求部署环境一次性改名。 @/env、@/*、@vite/*、next/navigation、next/link等 alias 保持一致。base、静态资源目录、favicon、字体和图片路径保持可配置。- Hash 路由、BrowserRouter 深层路由、iframe 嵌入路由和公开页面刷新都能正确加载资源。
- 开发端口与启动脚本可以通过环境变量覆盖,默认不与主开发工作区冲突。
5.3 构建模式
计划提供以下命令:
| 命令 | 用途 |
|---|---|
npm run dev / pnpm dev |
默认启动 Firefox 52 Rspack Dev Server,端口 5174 |
pnpm dev:firefox52 |
Rspack Dev Server,供 Firefox 52 直接调试 |
npm run dev:vite / pnpm dev:vite |
仅在现代浏览器调试时启动原 Vite Dev Server |
pnpm build:firefox52 |
Firefox 52 正式单目标构建 |
pnpm build:firefox52:fast |
不压缩、保留调试信息的快速验证构建 |
pnpm preview:firefox52 |
使用静态服务器验证正式产物 |
pnpm check:firefox52 |
扫描危险语法、资源路径和兼容清单 |
pnpm benchmark:firefox52 |
执行冷构建、热构建和增量构建基准 |
pnpm smoke:firefox52 |
运行 Firefox 52 核心页面与交互冒烟 |
pnpm smoke:firefox52:live |
运行真实普通问答流式冒烟 |
pnpm smoke:firefox52:agent-live |
选择当前可用智能体并运行真实流式冒烟 |
pnpm smoke:firefox52:themes |
验证 6 套主题 × 2 种布局 |
pnpm smoke:firefox52:full |
验证 118 个路由及可见非破坏性 Tabs |
类型检查继续单独运行 pnpm typecheck,不阻塞开发构建的模块转换。
6. JavaScript 与浏览器 API 兼容方案
6.1 兼容入口
建立唯一的 Firefox 52 兼容入口,并保证它早于 React、路由、请求客户端和业务模块执行。兼容入口统一处理:
Promise、Map、Set、Symbol、迭代器及必要的 core-js 能力。- AbortController、AbortSignal.timeout 和 abort reason 差异。
- ResizeObserver、IntersectionObserver、matchMedia 监听接口。
- ReadableStream、WritableStream、TransformStream。
queueMicrotask、globalThis、Object.fromEntries、Promise.finally等运行时能力。crypto.randomUUID、Clipboard、下载、全屏等能力的回退实现。requestIdleCallback、structuredClone等组件可能间接使用的 API。
所有 polyfill 必须具备能力检测,只在缺失时安装,避免重复覆盖浏览器实现。
6.2 流式请求专项
流式问答是兼容工作的 P0 项。Firefox 52 的网络层不能依赖现代 fetch().body.getReader(),需建立统一传输适配器:
- 现代浏览器继续使用现有 fetch/SSE/NDJSON 路径。
- Firefox 52 使用 XHR
onprogress增量读取responseText。 - 适配器统一处理 SSE、NDJSON、取消、超时、断线、服务端错误和 UTF-8 分片。
- LangGraph、普通问答、智能体问答、AI 写作、深度研究、会商、技能地址扫描等流式接口全部复用同一兼容层。
- 增加分片边界测试,覆盖半个 JSON、半个 UTF-8 字符、连续空行、最后一行无换行和中途取消。
6.3 不可直接转换的语法
以下内容不能只依赖 SWC 或 core-js,必须通过升级、降级、替代或固定补丁解决:
- BigInt 字面量及 BigInt 专用算法。
- 正则向后断言、Unicode property escapes 和不支持的正则 flag。
- Module Worker 和依赖原生 ESM 的 Worker。
- 运行时拼接后才生成的现代语法。
- 强依赖新浏览器 Web API 的第三方组件。
处理顺序:优先选择兼容版本,其次维护专用 fork,再使用 patch-package 或安装后补丁。构建期间的逐文件字符串替换只作为临时迁移手段。
6.4 产物静态扫描
check:firefox52 至少扫描:
- 未被打包的
import、export、import.meta。 - BigInt 字面量和
BigInt64Array/BigUint64Array直接依赖。 - 正则向后断言、Unicode property escapes、dotAll 等危险正则。
- 未处理的 async generator、module worker 和 module script。
- 绝对开发机路径、丢失的 chunk、错误 public path。
- HTML 中会被 Firefox 52 忽略且没有回退的入口脚本。
扫描结果必须支持白名单,白名单需要注明依赖、原因、验证方式和负责人,不能静默忽略。
7. 第三方依赖治理
7.1 依赖分级
建立 docs/firefox52-dependency-compatibility.md,按以下类别维护:
| 等级 | 含义 | 处理方式 |
|---|---|---|
| A | 原生兼容或经 SWC 即可兼容 | 正常打包 |
| B | 缺少 API polyfill | 加入统一兼容入口 |
| C | 包含可转换的新语法 | 加入 SWC 依赖 allowlist |
| D | 包含不可转换语法或新 API | 固定版本、fork、patch 或替换 |
| E | Firefox 52 平台能力无法完整支持 | 提供业务等价回退并记录差异 |
7.2 首批专项依赖
优先审计以下依赖:
- React 19、React DOM、React Router。
- LangGraph SDK、LangChain、AI SDK、LangSmith。
- Mermaid、Shiki、react-syntax-highlighter、Oniguruma。
- CodeMirror、Tiptap/ProseMirror、KaTeX、Marked、react-markdown。
- MapLibre GL、Leaflet、XYFlow、OGL、GSAP、Motion。
- Radix UI、TDesign React、cmdk、Embla。
- TanStack Query、Axios、Zod、date-fns、uuid。
- docx、file-saver 和文件预览相关模块。
重型模块保持路由级或组件级动态加载。Rspack 必须把动态 import 转为 Firefox 52 可用的普通 chunk loader。
8. CSS 与视觉一致性方案
8.1 CSS 构建顺序
CSS 建议按以下顺序处理:
- Tailwind 4 生成样式。
- 展平
@layer,防止 Firefox 52 忽略整组规则。 - 生成颜色和透明度回退。
- 处理嵌套、逻辑属性、选择器和可安全转换的现代语法。
- Lightning CSS 按 Firefox 52 目标转换。
- 生产模式压缩,开发模式保持未压缩和快速 source map。
需重点验证当前 rgb(var(--legacy-*-rgb) / alpha) 在 Firefox 52 中的实际表现;若浏览器不接受空格分隔和斜杠透明度语法,应在构建期生成逗号分隔的 rgba() 或直接颜色值。
8.2 手写兼容 CSS 与文件拆分
构建工具无法可靠转换,或者转换后仍存在布局和交互差异的样式,直接编写 Firefox 52 专用 CSS。兼容样式不得继续集中追加到 globals.css,统一放在独立目录中按职责拆分:
src/styles/firefox52/
├── index.css # 只负责按固定顺序汇总核心兼容样式
├── tokens.css # 颜色、透明度、阴影和主题变量回退
├── base.css # 浏览器基础差异和通用元素修正
├── layout.css # 页面框架、侧边栏、滚动区和响应式布局
├── overlays.css # Dialog、Popover、Select、Tooltip、Guide 等浮层
├── markdown.css # Markdown、代码块、公式、表格和引用
├── editors.css # CodeMirror、Tiptap、ProseMirror 等编辑器
├── visualizations.css # Mermaid、XYFlow、图表、地图和 Canvas 容器
├── chat.css # 普通问答、智能体问答和消息时间线
├── writing-research.css # AI 写作、深度研究和公文工作台
├── roundtable.css # 会商、流程图和报告协作
├── task-workspaces.css # 任务深链、目的树和快捷跳转栏
└── admin.css # 管理端表格、表单和配置页
拆分规则:
- 全局首屏必需的
tokens/base/layout/overlays由index.css统一引入。 - Markdown、编辑器、可视化、会商、任务工作区和管理端样式随对应路由或组件导入,让 Rspack 生成独立 CSS chunk,避免所有用户加载完整兼容样式。
- 单个兼容 CSS 文件建议控制在 500 行或未压缩 30 KB 以内;超过任一门槛时继续按组件或业务域拆分。
- HTML 根节点由兼容入口设置稳定标记,例如
data-browser-compat="firefox52"。兼容规则应挂在该标记下,防止影响现代浏览器和公共组件的默认样式。 - 优先复用语义 token 和现有组件 class,不复制整份第三方组件样式。只覆盖 Firefox 52 实际不兼容的声明。
!important只用于第三方组件无法通过正常层叠覆盖的场景,并在规则旁注明原样式来源和原因。- 文件加载顺序必须固定:主题 token → 基础样式 → 布局 → 通用浮层 → 业务页面。禁止依赖偶然的 chunk 到达顺序解决优先级。
- 每个文件明确对应验收页面,删除页面或修复上游兼容性时同步清理失效规则。
如果某个功能仅需要少量兼容规则,样式文件放在功能模块旁并使用 .firefox52.css 后缀;跨页面共用的兼容规则才放入 src/styles/firefox52/。构建检查需要统计各文件行数、体积、重复选择器和 !important 数量,超过门槛时提示拆分。
8.3 CSS 风险清单
建立自动扫描和人工验证清单,覆盖:
color-mix()、OKLCH、现代rgb()/hsl()。@layer、CSS nesting、container query。:has()、:focus-visible、复杂:is()/:where()。- Flexbox
gap、Grid 差异和subgrid。 aspect-ratio、inset、min()、max()、clamp()。dvh/svh/lvh、逻辑方向属性。backdrop-filter、mask、混合模式和复杂滤镜。- sticky、滚动容器、overscroll 和自定义滚动条。
- Portal 浮层、z-index、transform containing block 和
pointer-events。
无法可靠转换的布局功能通过兼容 utility 或组件级基础样式回退解决,不能只隐藏出错区域。
8.4 视觉回归范围
每种主题至少截取以下代表页面:
- 登录页和新对话落地页。
- 普通问答流式消息页。
- 智能体列表、创建页和智能体聊天页。
- AI 写作工作台。
- 多智能体会商三步工作台和流程图。
- 知识库列表、编辑器和知识图谱。
- 任务管理、目的树弹窗和快捷跳转栏。
- 管理端表格、Tabs、表单和确认弹窗。
- iframe 嵌入页和公开分享页。
- 站点预览、地图、图表和全屏场景。
视觉验收重点比较布局边界、间距、颜色、滚动区域、遮罩和弹层位置。截图自动化优先使用与 Firefox 52 匹配的 Selenium/geckodriver;无法稳定自动化的页面纳入人工截图清单。
9. 全功能验收矩阵
9.1 P0:必须首先打通
| 功能域 | 核心场景 |
|---|---|
| 登录与鉴权 | 密码登录、URL 参数登录、退出、刷新恢复、鉴权失效 |
| 页面框架 | 全量/简洁模式、侧边栏、菜单、主题、路由刷新 |
| 普通问答 | 新建会话、历史会话、流式回答、停止、重试、错误显示 |
| 消息展示 | Markdown、GFM、代码高亮、公式、链接、引用、流程图 |
| 文件 | 上传、附件卡片、产物预览、下载、Word 导出 |
| 智能体问答 | 智能体列表、进入聊天、新建和历史会话 |
| iframe | embed=1、hideJump=1、主题、独立鉴权、postMessage |
| 错误恢复 | 断网、接口 401/403/500、chunk 加载失败、刷新恢复 |
9.2 P1:主要业务能力
| 功能域 | 核心场景 |
|---|---|
| 智能体管理 | 创建、编辑、模型、知识空间、SOUL、技能、保存、引导 |
| 舆情分析智能体 | 外部流式接口、会话、错误信息 |
| AI 写作 | 经典版、对话版、阶段推进、干预、资料、Markdown 与 Word 下载 |
| 深度研究/公文 | 发起任务、过程状态、恢复、结果展示和下载 |
| 多智能体会商 | 普通、规划、8BF、岗位会商、链条配置、后台续跑 |
| 报告协作 | 会话列表、协作过程、结果编辑和导出 |
| 知识空间 | 列表、详情、上传、Markdown 编辑、Wiki、图谱、检索调试 |
| Notebook | 列表、详情、资料和生成流程 |
| 定时任务 | 任务列表、创建、运行详情、公开运行页 |
| 任务深链 | rwfx、3qfx、xdfx、agentfx、单智能体、会商、行动分区 |
| 任务报告 | 生成、文件卡片、入库确认、宿主通知 |
| 轻应用 | 应用列表、窗口打开、iframe 宿主、动态菜单 |
9.3 P2:管理、配置和扩展能力
- 用户、活动、记忆、模型、模型交换与并发配置。
- 智能体、技能、技能上下线、技能地址扫描/预览/替换/回滚。
- 菜单、简洁菜单、按钮、标签、固定问题、推荐问题、提示词前缀。
- 敏感词、排行榜、插件、岗位和岗位角色。
- 业务链、发布广场、私有广场、技能压缩、LLM 指标和 checkpoint 迁移。
- 公开分享、排行榜、会商报告、会商看板和定时任务全屏页面。
- Web App/Site Studio、地图、流程图、图表和沙箱 HTML 预览。
- 微信样式入口、无界嵌入和其他特殊页面壳。
9.4 单项验收规则
每个功能项必须记录:
- 入口 URL、角色和前置数据。
- 页面是否正常加载及首个可交互时间。
- 主操作、保存/提交、返回和刷新恢复结果。
- 是否涉及流式、上传、下载、Worker、Canvas、SVG、WebGL 或 iframe。
- Firefox 52 控制台错误和网络失败。
- 样式截图、已知差异和回退行为。
- 验收人、日期、构建 commit 和结果。
路由清单应由路由源码自动提取后与人工场景表合并,新增路由若未进入矩阵则 CI 提示失败。
10. 开发阶段
阶段 0:基线和可观测性
工作项:
- 固定 Node、pnpm、Firefox 52、Rspack/SWC 候选版本和测试机器信息。
- 记录 Vite legacy 的冷构建、热构建、增量构建、内存峰值和产物体积。
- 保存当前主要页面在现代浏览器和 Firefox 52 的截图、控制台错误及网络日志。
- 自动提取路由清单和动态 import 清单。
- 输出依赖语法扫描报告和浏览器 API 使用清单。
- 建立可重复执行的 benchmark 脚本,结果保存为 JSON 和 Markdown。
退出条件:任何人都能按文档复现当前构建时间和 Firefox 52 白屏/错误现状。
阶段 1:Rspack 并行构建骨架
工作项:
- 增加 Rspack 配置、HTML、静态资源、alias、环境变量和 public path。
- 接入内置 SWC,先处理项目源码,再逐步扩展到依赖 allowlist。
- 接入 React、CSS、字体、SVG、图片和动态 import。
- 建立
dev:firefox52、build:firefox52:fast和 preview 命令。 - 暂时保留 Vite legacy 命令作为对照和回退。
退出条件:Firefox 52 能通过 Rspack dev server 打开登录页和空工作区,没有语法错误与 chunk 加载错误。
阶段 2:运行时与流式链路
工作项:
- 重整统一兼容入口和 polyfill 顺序。
- 完成 XHR 流式适配器并接入核心请求路径。
- 验证取消、超时、错误解析、鉴权头和跨域行为。
- 处理 Web Worker、WebSocket、EventSource 和动态 chunk 加载。
- 完成普通问答端到端测试。
退出条件:普通问答可以连续完成发送、流式接收、停止、重试和刷新恢复。
阶段 3:依赖清理和固定补丁
工作项:
- 对首批专项依赖分级。
- 把现有 Vite 字符串补丁迁移为版本固定、fork、alias 或安装后补丁。
- 对 Mermaid、Shiki、Oniguruma、LangSmith、p-queue 等建立单独验收用例。
- 配置最终产物危险语法扫描。
- 为新增依赖增加 CI 扫描。
退出条件:生产产物通过静态扫描,补丁均有版本校验,依赖升级导致补丁失效时构建直接失败并给出清晰错误。
阶段 4:CSS 和组件样式兼容
工作项:
- 把现有 PostCSS/Tailwind/Lightning CSS 流程接入 Rspack。
- 建立
src/styles/firefox52/,按主题、布局、浮层和业务域拆分手写兼容 CSS,避免继续扩大globals.css。 - 配置核心兼容 CSS 与路由级兼容 CSS 的分包策略,并增加单文件行数、体积和重复规则检查。
- 修复主题颜色、透明度、cascade layer、flex gap 和现代选择器问题。
- 验证 TDesign、Radix、Tailwind 组件和 Portal 浮层。
- 建立 CSS 危险语法扫描与代表页面截图回归。
- 验证各主题和三种目标分辨率。
退出条件:P0 页面和代表组件没有布局塌陷、透明色失效、弹层错位或滚动锁死。
阶段 5:全功能逐批清零
按以下批次执行,每批都完成“功能、控制台、网络、样式、刷新恢复”五项检查:
- 登录、框架、普通问答和文件。
- 智能体管理与智能体问答。
- AI 写作、深度研究、公文。
- 多智能体会商、业务链和报告协作。
- 知识空间、Notebook、Markdown 编辑器和图谱。
- 任务深链、任务报告、轻应用和 iframe。
- 定时任务、管理端和设置页。
- 公开页面、Site Studio、地图、图表和其他扩展能力。
退出条件:P0、P1 全部通过,P2 完成验证;所有遗留项都有可执行的修复或等价回退方案。
阶段 6:构建性能专项优化
工作项:
- 开启并调优 Rspack 持久化缓存和增量构建。
- 开发模式关闭压缩,使用低成本 source map。
- 生产模式使用 SWC minimizer,CSS 使用 Lightning CSS minimizer。
- 缩小 SWC 转换范围,对不兼容依赖使用精确 allowlist。
- 对 Mermaid、Shiki、MapLibre、编辑器、会商等重型模块做路由级拆分。
- 检查重复依赖、barrel export、无效 locale 和大资源。
- 评估 lazy compilation;仅在不破坏 Firefox 52 chunk 加载时启用。
- 将耗时阶段输出到构建 profile,逐项消除长任务。
退出条件:达到第 3.2 节性能门槛,同时功能和样式回归无新增失败。
阶段 7:持续集成和离线部署衔接
工作项:
- CI 执行 typecheck、Rspack 构建、危险语法扫描、核心单测和冒烟测试。
- 保存构建时间趋势,超过阈值时提示回归。
- 固定包版本和校验值,保证离线环境可重复安装。
- 离线依赖与发布资产交由
knowledge-base-bj/deerflow-offline-deployment仓库维护,本业务仓库只保留源码和依赖清单。 - 更新启动脚本、部署文档、缓存策略和静态资源响应头。
退出条件:干净环境可以离线安装、构建、启动并通过 Firefox 52 冒烟测试。
阶段 8:切换与旧链路清理
工作项:
- 完成最终功能矩阵、视觉报告和性能报告评审。
- 将 Firefox 52 开发和构建命令切换到 Rspack。
- 删除已经被固定补丁替代的 Vite legacy 临时代码。
- 保留一段时间的 Vite 基准脚本,确认稳定后再彻底清理兼容分支中的旧依赖。
退出条件:连续多个提交未出现功能、样式和性能回归,Rspack 成为兼容分支唯一正式构建链。
11. 性能测试方法
每组测试至少执行 5 次,取中位数并记录 P95:
- 冷启动:删除构建缓存后启动开发服务器,测量到首页可请求时间。
- 热启动:保留缓存重启开发服务器。
- TSX 增量:修改一个叶子组件和一个高层布局组件。
- CSS 增量:修改组件样式和全局主题样式。
- 冷生产构建:删除 Rspack 缓存和 dist。
- 热生产构建:保留缓存、源码不变再次构建。
- 单文件生产变更:修改一个组件后重新构建。
记录字段:commit、构建模式、CPU、内存、磁盘、Node/pnpm 版本、总耗时、各阶段耗时、峰值内存、模块数量、chunk 数量、JS/CSS 体积和缓存命中率。
性能比较必须在相同机器和相同后台负载下进行。正式报告同时保留原始日志,避免只记录一次最佳结果。
12. 主分支同步策略
兼容分支需要持续接收正常业务开发,采用以下约束:
- 构建和兼容代码集中在独立目录与入口,减少对业务组件的侵入。
- 能通过适配器解决的问题不直接修改业务协议。
- 定期从
master-zg合并新功能,每次合并后自动更新路由和依赖扫描结果。 - 新增路由必须进入功能矩阵;新增依赖必须进入依赖兼容清单。
- 新增流式接口必须使用统一传输层,不能绕过 Firefox 52 XHR 回退。
- 新增主题和全局组件必须进入样式截图集。
- 冲突解决优先保留主分支业务逻辑,再在兼容层补充旧浏览器处理。
13. 风险与处理原则
| 风险 | 处理原则 |
|---|---|
| 第三方依赖停止支持旧浏览器 | 固定版本或维护兼容 fork |
| fetch 流式响应不可用 | XHR onprogress 统一回退 |
| Map/WebGL 能力差异 | 降级依赖或提供保持业务信息的二维/静态回退 |
| 编辑器、语法高亮和 Worker 依赖现代能力 | classic worker、主线程回退或兼容版本 |
| CSS 转换后仍存在布局差异 | 兼容 utility、组件基础样式和截图回归 |
| Polyfill 体积过大 | 单目标按需注入,重型功能路由级加载 |
| 兼容补丁随依赖升级失效 | 精确版本校验,失败时终止构建 |
| Rspack 插件兼容不足 | 优先使用内置能力,必要时编写小型 loader/plugin |
| 主分支持续新增功能 | 自动路由、依赖、API 和 CSS 扫描 |
| 旧浏览器自动化不稳定 | 自动冒烟与人工矩阵结合,保留截图和日志证据 |
14. 交付物
实施完成后应包含:
- Rspack 开发、快速构建和生产构建配置。
- Firefox 52 统一 polyfill 入口和流式传输适配器。
- 第三方依赖兼容清单及固定补丁。
- CSS 兼容流水线、扫描脚本和视觉基准图。
- 按职责拆分的 Firefox 52 手写兼容 CSS,以及对应的体积和重复规则检查。
- 路由级功能验收矩阵。
- 自动冒烟、危险语法扫描和构建性能脚本。
- 基线报告、最终性能对比报告和已知差异说明。
- 开发运行、离线构建、部署和故障排查文档。
15. 最终验收清单
- Firefox 52 开发服务器可直接打开并调试。
- 登录、导航、主题、路由刷新无白屏。
- 普通问答和智能体问答可以稳定流式输出。
- 上传、下载、Markdown、公式、代码、流程图和 Word 导出通过。
- AI 写作、研究、会商、知识库、任务深链等 P1 功能全部通过。
- 管理端、设置、公开页和扩展能力完成 P2 验证。
- 所有现有主题和目标分辨率完成视觉回归。
- 产物通过危险语法和资源路径扫描。
- 冷构建、热构建和增量构建达到性能门槛(冷/热生产构建已记录,增量构建仍需单独量化)。
- 连续构建与长时间运行无 chunk 丢失和内存异常。
- 新增功能与依赖具备持续兼容检查。
- 离线环境可以重复安装、构建和部署。