基于 umi3 升级到 umi4
以下是基于 umi3 升级到 umi4 的具体实现方案，结合物联网工具开发场景（需与 Evmars-Portal 组件复用），从技术迁移路径、关键适配点、收益分析三个方面展开说明。
一、技术迁移整体方案
1. 升级目标与约束条件
● 目标：
● 完成 umi3 → umi4 平滑升级，保留现有业务功能，同时利用 umi4 新特性优化开发体验（如组件复用、动态界面生成）。约束：兼容现有 React 业务代码（支持升级至 React 18）；
○ 保留 antd 组件库（建议同步升级至 antd 5.x）；
○ 确保物联网工具与 Evmars-Portal 的组件、状态管理、路由逻辑可复用。
二、分阶段实施步骤
阶段 1：环境与依赖升级（1-2 天）
核心任务：升级 umi 及关联依赖，确保基础环境兼容。
| 操作项 | 具体步骤 | 原因 / 说明 |
|---|---|---|
| umi 版本升级 | 1. 卸载 umi3：npm uninstall umi；2. 安装 umi4：npm install umi@latest | umi4 基于 ESM 重构，兼容现代前端工具链（如 Vite），构建速度提升 30%+ |
| React 升级至 18 | 1. 安装 React 18：npm install react@18 react-dom@18；2. 安装适配包：npm install @types/react@18 @types/react-dom@18 | umi4 原生支持 React 18，利用 Concurrent 模式优化复杂界面（如物模型动态表单）渲染性能 |
| antd 升级至 5.x | 1. 卸载 antd4：npm uninstall antd；2. 安装 antd5：npm install antd@latest；3. 按需引入样式（umi4 自动处理） | antd5 采用 CSS-in-JS（StyleProvider）+ 原子化 CSS，体积更小，与 umi4 的 CSS 优化（如 CSS Modules）更兼容 |
| TypeScript 版本对齐 | 升级 TS 至 4.9+（建议 5.0+）：npm install typescript@latest | umi4 对 TS 类型支持更严格，高版本 TS 可避免类型报错（如组件 Props 推导） |
阶段 2：配置文件迁移（1-2 天）
核心任务：将 umi3 配置迁移至 umi4，适配新配置规范。
| umi3 配置项 | umi4 适配方案 | 原因 / 说明 |
|---|---|---|
| config/config.js | 迁移至 src/config.ts（或 config/config.ts），并调整为 ESM 导出（export default） | umi4 推荐使用 TS 编写配置，支持类型提示；配置文件位置更灵活（支持 src 目录） |
| routes 配置式路由 | 逐步迁移至 文件路由（默认启用），保留部分配置式路由（通过 defineConfig 声明） | umi4 文件路由（src/pages 目录即路由）更符合现代前端规范，减少冗余配置；复杂路由（如权限控制）仍可通过配置式管理 |
| dva 状态管理 | 移除 @umijs/plugin-dva，替换为 jotai/zustand（轻量状态管理方案） | umi4 不再内置 dva，推荐更灵活的轻量库；物联网工具的状态（如设备实时数据）更适合原子化管理 |
| proxy 代理配置 | 保留在 config/config.ts 中，格式从 object 改为 Record<string, ProxyOptions> | umi4 代理配置支持更细粒度控制（如 changeOrigin、rewrite），适配物联网后端多环境联调需求 |
| theme 主题配置 | 通过 antd 的 ConfigProvider 或 umi 的 modifyVars 调整（推荐 antd5 的 token 定制） | antd5 支持动态主题（CSS 变量），与 umi4 的 @umijs/plugin-antd 插件深度集成 |
阶段 3：代码适配与组件复用（3-5 天）
核心任务：修复业务代码兼容问题，重点保障物联网工具与 Evmars-Portal 的组件复用。
| 适配场景 | 具体操作 | 原因 / 说明 |
|---|---|---|
| 路由逻辑迁移 | 1. 将 src/pages 目录下的文件按路由规则自动生成（如 src/pages/device → /device）；2. 复杂路由（如需要权限控制）通过 config/config.ts 的 routes 字段声明 | 文件路由减少手动配置，提升开发效率；物联网工具的动态界面（如物模型生成的页面）可通过文件路由自动注册 |
| 状态管理迁移 | 1. 移除 dva 的 models 目录；2. 用 jotai 原子化状态替代（示例）：tsx // src/store/device.ts import { atom } from 'jotai'; export const currentDeviceAtom = atom(null); 3. 在组件中通过 useAtom 访问状态 | Jotai 轻量（体积仅 2KB）、原子化，适合物联网工具中设备状态、物模型数据等细粒度状态管理；与 Evmars-Portal 共享状态更简单 |
| antd 组件适配 | 1. 修复 Form 组件的 form 属性（umi3 用 getFieldDecorator，umi4 推荐 useForm）；2. 替换 Icon 组件（antd5 推荐 @ant-design/icons 直接导入）；3. 调整样式类名（antd5 移除 ant- 前缀，改为 antd-） | antd5 组件 API 更现代化（如 Form 的 hooks 化），与 umi4 的 TS 类型检查更匹配；物联网工具的表单（如物模型属性配置）可直接复用 Portal 的 BaseForm 组件 |
| 动态界面生成适配 | 1. 利用 umi4 的 import() 动态导入组件（如物模型生成的组件）；2. 通过 React.lazy 实现懒加载：tsx const DynamicComponent = React.lazy(() => import(./components/${modelType})); |
umi4 支持 ESM 动态导入，配合 React.lazy 优化物联网工具中大量动态组件的加载性能 |
| 与 Portal 组件复用 | 1. 将公共组件（如 DeviceStatusIndicator、SensorChart）抽离为独立包（@evmars/portal-components）；2. 在 umi4 项目中通过 npm link 或 pnpm workspace 引用 | umi4 对外部依赖的 ESM 支持更好，避免组件复用时代码冗余；物联网工具可直接使用 Portal 的导航栏、菜单等基础组件 |
阶段 4：测试与优化（1-2 天）
核心任务：验证功能完整性，优化性能与开发体验。
| 操作项 | 具体步骤 | 原因 / 说明 |
|---|---|---|
| 兼容性测试 | 1. 测试旧功能（如物模型表单提交、命令下发）是否正常；2. 验证与后端接口（配置 Json、物模型）的兼容性 | umi4 构建产物为 ESM，需确保后端接收的请求头、参数格式与旧系统一致 |
| 性能优化 | 1. 启用 umi4 的 mfsu（模块联邦加速）；2. 配置 splitChunks 拆分公共组件；3. 对物模型动态组件添加 React.memo 缓存 | mfsu 可提升 50% 以上构建速度；拆分公共组件减少重复打包，适配物联网工具多页面场景 |
| 开发体验优化 | 1. 配置 umi dev 的 HMR（热更新）规则（如修改物模型组件时仅刷新当前界面）；2. 集成 storybook 独立调试公共组件 | umi4 的 HMR 更稳定，减少开发时的页面刷新；Storybook 可独立预览组件，方便与 Portal 团队同步组件状态 |
三、升级 umi4 的核心收益
1. 开发效率提升
● 文件路由：减少手动配置路由的工作量，尤其适合物联网工具中大量动态生成的界面（如按物模型自动生成的页面）；
● 轻量状态管理：Jotai/Zustand 比 dva 更简单，降低新成员上手成本；
● 组件复用：umi4 对 ESM 的原生支持，使跨项目组件共享（如与 Portal 的 BaseTable、DeviceCard）更稳定。
2. 应用性能优化
● 构建速度：umi4 基于 Vite 优化，冷启动时间降低 40%，热更新时间缩短至 500ms 内（适合物联网工具频繁修改物模型的场景）；
● 运行时性能：React 18 的 Concurrent 模式可优先渲染关键界面（如设备状态监控），避免长列表（如传感器数据）卡顿；
● 体积优化：antd5 原子化 CSS + umi4 的 tree-shaking 可减少 30% 以上的 CSS 体积，提升工具加载速度（尤其在低网络环境下）。
3. 扩展性与未来兼容性
● 插件体系：umi4 插件支持 ESM 导入，可灵活扩展物联网专属功能（如物模型解析插件、WebSocket 通信插件）；
● 现代特性支持：支持 App Router（实验性）、React Server Components（未来可适配物联网工具的服务端渲染需求）；
● TypeScript 友好：umi4 配置、组件 Props 均支持 TS 类型推导，减少物联网复杂业务（如多类型物模型字段）的类型错误。
四、风险与应对方案
| 风险点 | 应对方案 |
|---|---|
| 旧插件不兼容（如 @umijs/plugin-dva） | 替换为 jotai/zustand，或寻找 umi4 兼容的插件（如 @umijs/plugins 官方库） |
| 路由迁移导致页面 404 | 先保留配置式路由，逐步迁移文件路由；通过 umi dev 的路由调试工具（/umi-dev/routes）检查路由映射 |
| antd5 样式冲突（与 Portal） | 统一使用 ConfigProvider 配置主题（如 token），确保物联网工具与 Portal 样式一致 |
| 动态组件加载失败 | 为 React.lazy 添加错误边界（ErrorBoundary 组件），避免单个组件异常导致整个界面崩溃 |
总结
升级至 umi4 是物联网工具开发的关键技术迭代，既能提升开发效率与应用性能，又能更好地与 Evmars-Portal 复用组件。建议优先完成依赖与配置迁移，再逐步适配核心业务代码，最后通过测试验证稳定性。