#13447·umi

[Feature Request] Utoopack lazyDynamicImports 首次加载期间显示编译状态

Author: fireairforceCreated Sep 17, 2026Updated Sep 17, 2026

问题

Umi 开启 Utoopack 的 lazyDynamicImports 后,首次打开开发页面会触发按需编译。在这段等待时间里,页面只有应用自身的 loading,没有提示 Utoopack 正在编译,用户无法区分是在加载业务数据还是等待构建。

期望在开发环境的 loading 阶段显示明确的编译状态,例如 Utoopack is compiling...,编译完成后自动消失。保留应用已有的 loading,不需要替换成整页加载页,也不要为了显示状态而关闭懒编译。

环境和复现方向

本地使用 @umijs/bundler-utoopack + @utoo/[email protected]。配置:

typescript
export default {
  utoopack: {
    devServer: {
      dynamicHmrChunkLists: true,
      lazyDynamicImports: true,
    },
  },
};
  1. 在具有动态导入路由的 Umi 应用中开启上述配置。
  2. 冷启动 dev server,首次打开页面。
  3. 当入口或路由动态模块仍在编译时,页面应明确显示编译状态;目前没有这一提示。

可从仓库 examples/with-antd-5 开始验证。为了稳定观察,可以给懒模块配置一个有延时的测试 loader,确保是真实编译耗时,而不只是网络下载延迟。

已确认的代码缺口

  • packages/bundler-utoopack/client/client/client.js 已定义 BUILDING / BUILT,但 handleMessage 中的 case ACTIONS.BUILDING: 直接 break,没有任何 UI 更新。
  • @utoo/packpackages/pack/src/core/hmr.tsproject.updateInfoSubscribe(30) 的 start/end 分支发送 building / built
  • Umi 的 packages/preset-umi/src/features/devTool/devTool.ts 只在 api.appData.bundleStatus.done 为 false 时返回启动状态页。
  • packages/bundler-utoopack/src/index.ts 在初始 serve() ready 后调用 onDevCompileDone。这时初始构建完成不代表后续首次访问触发的懒编译也已完成,因此仅依赖启动状态页无法覆盖这个阶段。

需要一起验证的启动时序

packages/bundler-utoopack/src/config.tswriteUtoopackOverlayEntry 通过动态 import 链先加载 client.js,再加载应用入口。打开 lazyDynamicImports 后,开发提示客户端本身也可能被懒编译。

需要确认提示客户端和 WebSocket 是否能在首次应用懒编译开始前就绪,以及连接建立时是否会漏掉已经发送的 building。只补 BUILDING 分支可能仍遗漏最早的一段等待,不能仅靠模拟消息的单测认定整个首次打开流程已解决。

排查证据及范围

  • 用浏览器暂停 examples/with-antd-5 的 lazy-compilation manifest 请求时,可以观察到等待期间没有编译状态文字,放行后应用正常显示。这只验证了等待阶段的展示缺口,不是冷编译耗时测量。
  • 将真实客户端脚本放进 VM 测试环境,发送 building 后断言存在编译提示,测试在当前实现下失败。
  • 用户明确说明主要需求是“已有 loading 时增加 Utoopack 正在编译的状态”,不应将本 issue 理解为业务白屏或构建失败。
  • 尚未完成真实冷启动下的编译消息时序验证,也未提交修复。

建议实现和验收

  • 在现有 Utoopack 开发客户端中消费编译状态,显示一个独立、非阻塞的提示;复用现有连接,避免额外建立 WebSocket。
  • 以真实编译状态为准,不把所有 loading 都标记为编译;可加短暂延迟,避免极短构建闪烁。
  • 首次打开的懒编译期间可以看到提示,完成后消失,已有应用 loading 保持正常。
  • 验证客户端尚未连接、重复 building 消息、快速完成、编译失败及连接断开时的状态清理;不能残留提示或误触发页面刷新。
  • 保持错误 overlay、恢复行为和 HMR 正常;生产构建不包含开发提示。
  • 为客户端消息处理增加回归测试,并通过带真实延时 loader 的浏览器验证覆盖首次打开场景。

相关 Utoopack 特性: https://github.com/utooland/utoo/pull/3358