358 lines
19 KiB
Markdown
358 lines
19 KiB
Markdown
# 启动拆包与工具栏状态经验总结
|
||
|
||
更新日期：2026-04-21
|
||
|
||
## 这轮最值得记住的规律
|
||
|
||
### 1. 启动进度只能有一个“百分比真源”
|
||
|
||
这轮 loading 卡顿感的根因，不是进度条本身，而是进度来源混杂：
|
||
|
||
- HTML 启动壳自己在写阶段百分比
|
||
- 主线程初始化阶段也在写百分比
|
||
- Service Worker 又在回传资源进度
|
||
|
||
结果就是进度条会“跳”“卡”“倒像是更慢了”。
|
||
|
||
更稳的做法是：
|
||
|
||
- `SW` 未就绪前，只做短时间平滑模拟，让用户知道系统在工作
|
||
- `SW` 一旦开始回传进度，就由 `SW` 接管后半段百分比
|
||
- 其余阶段只更新文案，不再写数值
|
||
|
||
一句话：文案可以多源，百分比只能单源。
|
||
|
||
### 2. 懒加载要区分“触发器”和“内容体”
|
||
|
||
这轮多个两击问题，本质都和这个边界有关：
|
||
|
||
- 可以延后的是抽屉内容、弹窗内容、工具窗口内容
|
||
- 不该延后的是用户第一下要点到的按钮、触发器、壳层容器
|
||
|
||
如果把触发器本身也放进懒加载链路，第一次点击就可能只完成“挂载按钮/挂载容器”，第二次点击才真正打开内容，用户会直接感知成 bug。
|
||
|
||
推荐原则：
|
||
|
||
- 按钮、抽屉骨架、输入框外壳常驻
|
||
- 重内容、重依赖、低频模块按需挂载
|
||
- 首次点击允许局部 loading，但不允许“点击无响应”
|
||
|
||
### 3. 依赖编辑器上下文的组件，不能被随意挪出树外
|
||
|
||
这轮 `AI 图片生成` 报 `useBoard must be used inside <Plait>`，本质是把依赖 `Plait` 上下文的对话框，移到了错误的挂载层级。
|
||
|
||
经验是：
|
||
|
||
- 凡是依赖 `useBoard()`、`useDrawnix()`、选择态、画布上下文的组件
|
||
- 在做延迟加载、拆层、抽离壳层时
|
||
- 先确认它依赖的 Provider / Board Context 还在不在上游
|
||
|
||
尤其是：
|
||
|
||
- 对话框懒加载
|
||
- 抽屉懒加载
|
||
- “核心画布壳层 / 延后功能层”拆分
|
||
|
||
如果组件依赖的是“当前画布实例”，那它的懒加载位置必须仍在画布上下文树内。
|
||
|
||
### 4. `setState(updater)` 里不要顺手改别的面板状态
|
||
|
||
左侧“项目 / 工具箱 / 任务面板”要点两下的问题，根因不是点击事件丢了，而是 toggle 逻辑写成了：
|
||
|
||
- 在 `setState(prev => ...)` 的 updater 里
|
||
- 顺手调用 `closeAllDrawers()`
|
||
- 于是一次点击里混进了多份状态更新
|
||
|
||
这种写法在互斥面板场景里很容易让首击状态被冲掉。
|
||
|
||
更稳的方式是显式顺序化：
|
||
|
||
1. 先判断目标当前是否已打开
|
||
2. 如果要打开，先关闭其它互斥面板
|
||
3. 最后再打开目标面板
|
||
|
||
一句话：updater 里只算当前值，不做跨状态副作用。
|
||
|
||
### 5. 左侧常驻工具栏的顺序，不能跟“最近激活顺序”绑定
|
||
|
||
这轮另一类体验问题是：左侧常驻工具点一下就换位。
|
||
|
||
根因不是图标组件，也不是 `selected` 高亮，而是工具栏数据源按 `activationOrder` 排序：
|
||
|
||
- 工具一打开 / 一恢复，激活顺序就刷新
|
||
- 工具栏再按这个顺序重排
|
||
- 用户看到的就是“按钮自己跑了”
|
||
|
||
对常驻工具栏来说，用户心智更接近“固定栏位”，不是“最近使用列表”。
|
||
|
||
所以更合理的规则是：
|
||
|
||
- pinned 工具始终保持既有栏位顺序
|
||
- 打开后只替换本栏位的状态
|
||
- 非 pinned 的临时实例再单独排到后面
|
||
|
||
一句话：常驻栏看重空间记忆，不看重最近激活。
|
||
|
||
### 6. 版本更新后的懒加载 chunk 失效，要有“一次性自恢复”
|
||
|
||
这次 `DrawnixDeferredRuntime` 的报错：
|
||
|
||
- `Failed to fetch dynamically imported module`
|
||
|
||
本质不是业务逻辑错误，而是用户页面停留在旧版本，部署后旧 HTML / 旧运行时还在引用已经失效的 hash chunk。
|
||
|
||
这类问题的特点是：
|
||
|
||
- 用户刷新前一切正常
|
||
- 一旦触发某个 `React.lazy()` 模块才爆
|
||
- 报错看起来像功能坏了，实际是版本切换窗口里的静态资源失配
|
||
|
||
更稳的处理方式不是把所有懒加载都改成手写 loader，而是补一层轻量兜底：
|
||
|
||
- 在 `ErrorBoundary` 里识别动态导入 / chunk 失效错误
|
||
- 按“当前版本 + 当前模块”做一次性重试标记，避免死循环
|
||
- 自动刷新一次，并带时间戳参数绕过旧缓存
|
||
- 应用成功启动后再清理恢复参数，避免 URL 污染
|
||
|
||
一句话：发布后 chunk 失效不是“要不要刷新”的问题，而是“要不要帮用户只刷新一次并避免循环”的问题。
|
||
|
||
## 这轮适合沉淀成默认规则的做法
|
||
|
||
- 启动进度：前半段可模拟，后半段由资源进度单源接管
|
||
- 懒加载：只懒内容，不懒触发器
|
||
- 组件拆层：先确认上下文依赖，再移动挂载位置
|
||
- 互斥面板：显式开关，不在 updater 内联副作用
|
||
- 常驻工具栏：固定顺序优先于最近激活
|
||
- 版本切换：懒加载 chunk 失效时自动恢复一次，但必须有防循环保护
|
||
|
||
## 后续开发检查清单
|
||
|
||
- 这个 loading 百分比现在到底是谁在写？
|
||
- 这个入口第一次点击，是打开内容，还是只完成挂载？
|
||
- 这个懒加载组件是否依赖画布 / Provider 上下文？
|
||
- 如果新版本刚发布，这个懒加载失败是不是“旧页面引用失效 chunk”而不是业务异常？
|
||
- 这个 toggle 是否在 updater 里偷偷改了别的 state？
|
||
- 这个工具栏是“固定栏位”还是“最近使用列表”？排序规则是否和用户心智一致？
|
||
|
||
## 一句话总结
|
||
|
||
这轮真正值钱的经验不是“把 bug 修掉了”，而是明确了 6 条边界：
|
||
|
||
- 百分比单源
|
||
- 触发器常驻
|
||
- 上下文不丢
|
||
- toggle 不串副作用
|
||
- 常驻栏位不乱跳
|
||
- 失效 chunk 只自恢复一次
|
||
|
||
---
|
||
|
||
## 2026-05-17：首屏壳层拆分与 chunk 守门经验
|
||
|
||
### 现象
|
||
|
||
- 首屏慢不只来自代码体积，也可能来自运行时静态环和 chunk 归属错误。
|
||
- 这轮真正卡住构建的，不是业务组件本身，而是 `ai-chat` 和 `tool-windows` 之间被常量文件、服务入口、懒加载边一起拉成了静态回边。
|
||
- 纯工具函数如果和会反向依赖 `data/image` 的运行时模块放在同一个文件里，循环会在源码层先炸，然后再在 chunk 层放大。
|
||
|
||
### 架构变更
|
||
|
||
- `apps/web/src/main.tsx` 只保留最早期恢复与 bootstrap 入口，后续应用初始化下沉到 `bootstrap.tsx`。
|
||
- `Drawnix` 拆成首屏壳层和延后功能层，任务恢复、自动插入、字体/视频恢复等副作用交给 idle 启动器。
|
||
- 动态导入失败恢复独立到 `lazy-asset-recovery.ts`，避免首屏入口顺手背上重恢复逻辑。
|
||
- 图片自然尺寸这类轻量能力单独下沉到纯工具模块，`utils/image.ts` 只保留导出和编辑逻辑。
|
||
- `tool-ids.ts` 这类纯常量不能被目录级 `tool-windows` 规则误收编，否则很容易把轻量调用侧拖回重 chunk。
|
||
- 构建后校验不再只看入口 HTML，还要看入口静态依赖链、chunk SCC 和首屏 500KB 预算。
|
||
|
||
### 经验
|
||
|
||
- 先修运行时循环，再谈 chunk 瘦身。
|
||
- manualChunks 是分包守门，不是架构补丁。
|
||
- 纯常量、纯工具、纯类型文件尽量留在低层共享入口，别让它们进入重运行时桶。
|
||
- 首屏建议目标 200-300KB 未压缩，500KB 作为硬上限。
|
||
- 构建校验脚本最好同时守三件事：入口链、chunk 环、首屏体积。
|
||
- 当环只剩纯常量误入重 chunk 时，先给低层入口加分包例外，再考虑继续拆模块。
|
||
|
||
### 复盘清单
|
||
|
||
- 这个文件是不是既做纯工具，又回引了运行时服务？
|
||
- 这个常量是不是被错误分到重 chunk 里了？
|
||
- 这个懒加载边界是不是只该延后内容，不该拖延触发器？
|
||
- 构建守门脚本有没有把“能跑”升级成“能跑且不超预算”？
|
||
|
||
后面继续做启动性能和工具系统时，只要这 6 条不破，很多体验问题都会提前消失。
|
||
|
||
---
|
||
|
||
## 2026-04-22：SW 空闲预取与常驻工具条恢复经验
|
||
|
||
### 现象
|
||
|
||
- 左侧常驻工具 icon 只有在点开工具抽屉后才出现
|
||
- `SW` 日志显示已经激活，但页面侧 `SWChannelClient` 多次初始化超时
|
||
- 开发态 `idle-prefetch-manifest.json` 缺失，`prefetchIdleGroups` 直接中止
|
||
|
||
### 根因
|
||
|
||
- 页面把“有 `controller`”误当成“有可用 `Service Worker`”，但实际存在 `ready.active` 已激活、页面仍未被 controller 接管的窗口期
|
||
- 常驻工具条显示链路和完整 `tool-window runtime` 启用链路绑死，导致“显示 icon”也被重运行时阻塞
|
||
- UI 又额外依赖 `tool-windows` 分组预取完成信号，开发态 manifest 缺失时就会一直卡住
|
||
- `idle prefetch` 单次跑批如果人为截断，完成状态就会长期失真，最后只能靠超时兜底
|
||
|
||
### 最终方案
|
||
|
||
- `SWChannelClient` 初始化放宽为：`controller` 或 `navigator.serviceWorker.ready.active` 任一可用即可建通道
|
||
- 常驻工具条拆成两段：
|
||
icon 显示单独启用；点击 icon 时再按需启完整 `tool-window runtime`
|
||
- `toolWindowService` 恢复 launcher 状态时优先读取完整工具定义，保证首屏图标和标题完整
|
||
- `SW` 在 `activate` 后自动消费 idle prefetch 默认分组，并把完成状态广播给页面
|
||
- 页面监听 `SW_IDLE_PREFETCH_STATUS`，但只把它当优化信号；超时后直接放行常驻工具条，避免功能被优化链路反向阻塞
|
||
- `idle prefetch` 仍用小并发，但不能再裁剪总任务数，否则完成分组永远不闭环
|
||
|
||
### 这次最值得固化的规则
|
||
|
||
- `Service Worker` 可用性判断要区分：
|
||
`controller` 是“当前页已受控”，`ready.active` 是“后台已有可用 worker”，两者不是一回事
|
||
- 首屏可见能力和重运行时能力要解耦：
|
||
先让用户看到、点得到，再做按需增强
|
||
- 预取状态只能作为加速信号，不能作为功能显示前置条件
|
||
- 开发态缺 manifest、生产态资源回源失败，都要保证 UI 有可退化路径
|
||
|
||
### 排障顺序建议
|
||
|
||
1. 先看 `navigator.serviceWorker.controller` 和 `navigator.serviceWorker.ready.active` 是否分叉
|
||
2. 再看显示链路是否被 runtime 初始化、manifest、预取完成状态串联阻塞
|
||
3. 最后才看图标数据源、launcher 恢复、工具定义是否缺字段
|
||
|
||
---
|
||
|
||
## 2026-04-26：SW 关闭场景下的通道初始化超时经验
|
||
|
||
### 现象
|
||
|
||
- 控制台持续出现 `[SWChannelClient] Attempt 4 failed: Error: SW activation timeout`
|
||
- 调试状态里 `supported: true`，但 `controller: null`、`registration: null`
|
||
- 本地开发默认关闭 SW 或 URL 带 `?sw=0` 时仍然触发了 `swChannelClient.initialize()`
|
||
|
||
### 根因
|
||
|
||
- 页面只用“浏览器支持 `serviceWorker`”判断是否启动 SW 诊断链路，没有复用真正的 SW 启用开关
|
||
- `sw-console-capture` 为了尽早捕获日志，会主动初始化 `swChannelClient`，结果在 SW 未注册时反复等待不存在的 `controllerchange`
|
||
- SW 通道自身没有识别 `?sw=0`，其他调用点即使绕过主入口，也可能重新进入初始化重试
|
||
- 日志队列在通道不可用时只进不出，虽然单条较小，但长期打开页面会形成不必要内存占用
|
||
|
||
### 固化规则
|
||
|
||
- SW 相关入口必须共享同一个开关语义：
|
||
生产和本地调试默认启用；`?sw=0` 显式关闭；本地默认启动命令必须同步 watch 最新 `sw.js`
|
||
- 调试、崩溃、控制台捕获这类旁路能力，不能因为“想诊断 SW”而绕过 SW 开关主动拉起通道
|
||
- `SWChannelClient.initialize()` 自身也要兜底识别 `?sw=0`，避免未来新增调用点造成重复超时
|
||
- 离线日志队列必须有容量上限，通道不可用时丢弃最旧项，不能无限积压
|
||
- 控制台捕获要过滤 `[SWChannelClient]`、`[ServiceWorkerChannel]` 这类自身通道日志，避免错误日志再次驱动初始化与上报
|
||
|
||
### 排障顺序建议
|
||
|
||
1. 先看当前 URL 是否带 `?sw=0`，以及本地是否正在 watch 最新 `sw.js`
|
||
2. 再看是否存在 `registration`；如果没有注册，不要继续等 `controllerchange`
|
||
3. 最后排查是谁调用了 `swChannelClient.initialize()`，优先检查控制台捕获、崩溃上报、调试面板等旁路链路
|
||
|
||
---
|
||
|
||
## 2026-04-27：左侧浮岛工具栏与抽屉联动经验
|
||
|
||
### 现象
|
||
|
||
- 用户浏览器或系统存在左侧边缘标签时，固定贴边工具栏容易误触冲突。
|
||
- 直接把工具栏整体外移虽然能避让，但看起来像布局 bug，破坏“贴边悬浮岛”的原始观感。
|
||
- 将工具栏改成可拖动后，拖动过程中任务队列抽屉会被关闭态动画带出来。
|
||
- 任务队列抽屉从屏幕边缘大幅滑入，动画过重；抽屉打开后，左侧画布底色和抽屉底色割裂。
|
||
- 顶部拖动把手、底部固定按钮区如果只改父容器圆角，局部背景仍会把圆角视觉盖平。
|
||
|
||
### 根因
|
||
|
||
- “避让侧边标签”是用户个体环境问题，不适合用全局默认外移解决。
|
||
- 工具栏位置、抽屉位置、提示浮层位置、画布 fit-frame 避让如果各自写死宽度，拖动后必然错位。
|
||
- 关闭态抽屉的 `transform` 依赖工具栏右边界变量时，拖动工具栏会触发关闭态抽屉过渡，形成“被拖出来”的错觉。
|
||
- 任务队列抽屉和工具箱共用基础抽屉，但任务队列内容更重，应该用更轻的专属 motion。
|
||
- 抽屉只从工具栏右侧开始绘制时，工具栏左侧仍露出画布底色；抽屉色和画布色差会被用户感知成断层。
|
||
|
||
### 最终方案
|
||
|
||
- 默认仍贴屏幕左边缘，保持悬浮岛观感；只提供顶部拖动把手，让需要避让的用户手动拖入内侧。
|
||
- 工具栏横向位置用 `localStorage` 轻量持久化，双击把手复位到默认贴边位置。
|
||
- 统一维护 `--aitu-toolbar-left` 和 `--aitu-toolbar-right-edge`，抽屉、提示、fit-frame 都读同一套右边界。
|
||
- 拖动过程中只更新 CSS 变量和 DOM style，拖动结束后再落 React state，减少高频重渲染。
|
||
- 关闭态抽屉从 `translateX(-100%)` 隐藏，打开态再平移到工具栏右边界；拖动期间给根节点加 `aitu-toolbar-dragging` 禁用抽屉 transition。
|
||
- 任务队列抽屉使用轻量淡入：
|
||
`160ms transform + 120ms opacity`，关闭态保持 `visibility: hidden` 和 `pointer-events: none`。
|
||
- 抽屉打开时用同色 `box-shadow` 向左铺到屏幕边缘，工具栏 z-index 高于抽屉，让工具栏仍像浮在抽屉上。
|
||
- 工具栏底部固定区也要继承底部圆角，避免底部按钮区背景把父容器圆角盖平。
|
||
|
||
### 固化规则
|
||
|
||
- 默认位置优先保留产品最自然的视觉形态；兼容特殊环境时优先给用户可调能力，不要把所有用户都推到次优默认。
|
||
- 可拖动 UI 的高频 pointer move 不要每帧依赖 React state；能用 CSS 变量同步的位置，优先走 CSS 变量。
|
||
- 所有依赖工具栏边界的组件必须共享同一来源，不能散落硬编码宽度。
|
||
- 隐藏态元素如果跟随一个高频变化变量，要么禁用 transition，要么让隐藏态不依赖这个变量。
|
||
- 抽屉“内容从哪里开始”和“背景铺到哪里”可以分离：内容对齐工具栏，背景可延展到屏幕边缘。
|
||
- tooltip 只负责展示提示，不应接收 pointer events 挡住工具按钮点击。
|
||
- 改圆角时要检查内部固定区域、底部区域、滚动区域背景是否覆盖父容器弧度。
|
||
|
||
### 回归检查清单
|
||
|
||
- 默认桌面视口：工具栏 `left = 0`，右边界 CSS 变量等于工具栏实际右边界。
|
||
- 拖动把手：拖动时任务抽屉不外露，松手后位置持久化，双击可复位。
|
||
- 任务队列：首次打开有轻量动画，关闭态不可见且不可点击。
|
||
- 工具箱 / 项目抽屉 / 任务队列：打开后左边缘贴齐工具栏右边界。
|
||
- 抽屉打开后：工具栏左侧到屏幕边缘为抽屉同色背景，工具栏仍在上层。
|
||
- 移动端：不显示拖动把手，默认收起形态不变。
|
||
|
||
---
|
||
|
||
## 2026-04-27：右侧停靠工具栏与双向抽屉经验
|
||
|
||
### 现象
|
||
|
||
- 工具栏只允许拖到左侧内缘时，右手用户或右侧工作流无法获得同等避让能力。
|
||
- 工具栏拖到右侧后，项目/工具箱/任务抽屉如果仍向右展开，会被屏幕边界截断。
|
||
- 对话抽屉、小地图、缩放控件如果只按“右屏幕边缘”定位，会被右侧工具栏遮挡。
|
||
- 对话抽屉收起态如果只平移，不做 `visibility` / `pointer-events` 隐藏，右侧仍会露出面板边缘。
|
||
- 抽屉内容对齐工具栏后，抽屉背景没有铺满到屏幕边缘时，会出现画布色和抽屉色断层。
|
||
|
||
### 根因
|
||
|
||
- 工具栏位置从“左边界变量”升级为“双侧停靠语义”后，依赖它的浮层也必须知道当前停靠方向。
|
||
- 右侧停靠时，遮挡区域不是工具栏右边界，而是 `viewportWidth - toolbarLeft`。
|
||
- 抽屉宽度、抽屉展开方向、导航控件避让、fit-frame 可视区计算，不能各自用硬编码边距。
|
||
- 关闭态元素跟随工具栏位置时，仅靠 `transform` 容易在边缘露出残影或接收交互。
|
||
|
||
### 最终方案
|
||
|
||
- 工具栏可拖到屏幕最右侧，超过屏幕中线后在根节点标记 `aitu-toolbar-dock-right`。
|
||
- 继续用轻量 CSS 变量同步布局，不新增配置实体：
|
||
`--aitu-toolbar-left`、`--aitu-toolbar-right-edge`、`--aitu-toolbar-right-dock-width`、`--aitu-toolbar-right-avoidance`、`--aitu-toolbar-side-panel-max-width`。
|
||
- 右侧停靠时，项目/工具箱/任务抽屉向左展开，关闭态从屏幕外隐藏，打开态左边缘贴齐工具栏左侧。
|
||
- 右侧停靠的抽屉用同色 `box-shadow` 向屏幕边缘延展背景，内容对齐和背景铺满分离处理。
|
||
- `SideDrawer` 的 resize 方向按停靠侧切换；右侧停靠时拖左边缘调整宽度。
|
||
- `ChatDrawer` 右侧停靠时让出工具栏宽度，打开态背景铺到屏幕右边缘，关闭态使用 `opacity + visibility + pointer-events` 彻底隐藏。
|
||
- `ViewNavigation` / 小地图同时避让工具栏占位和打开的对话抽屉；fit-frame 按左右遮挡分别计算可视区。
|
||
- 顶部拖拽把手默认态进一步弱化，只在 hover、focus、dragging 时增强。
|
||
|
||
### 固化规则
|
||
|
||
- 可拖动悬浮工具栏一旦支持跨屏停靠，所有依赖边界的组件都要读统一 CSS 变量，不再假设工具栏永远在左侧。
|
||
- 判断抽屉展开方向应基于工具栏中心点所在半屏，而不是用户最后一次拖动方向。
|
||
- 右侧停靠时，导航控件的避让值要叠加工具栏宽度和已打开抽屉宽度，避免小地图被抽屉压住。
|
||
- 关闭态抽屉必须同时处理视觉隐藏和交互隐藏：`visibility: hidden`、`pointer-events: none`、必要时配合 `opacity`。
|
||
- 抽屉背景延展可以用同色阴影铺屏，但不要让内容区域跟着铺满，否则会破坏对齐和可读性。
|
||
- 改动右侧面板时，要同步回归 ChatDrawer、ViewNavigation、Minimap、fit-frame 和各类 toolbar-right 抽屉。
|
||
|
||
### 回归检查清单
|
||
|
||
- 工具栏拖到右边缘：工具栏不出屏，刷新后位置保留。
|
||
- 右侧工具栏打开项目/工具箱/任务抽屉：抽屉向左展开，不被屏幕裁切，背景铺到右侧屏幕边缘。
|
||
- 对话抽屉关闭态：面板不可见且不可点击，只保留把手。
|
||
- 对话抽屉打开态：右侧让出工具栏宽度，背景延伸到屏幕右侧。
|
||
- 对话抽屉打开 + 小地图展开：小地图和缩放控件避开“工具栏 + 对话抽屉”组合宽度。
|
||
- fit-frame：工具栏/抽屉在左侧或右侧时，Frame 都居中到剩余可视区。
|