从独立 dva 迁移到 Umi：集成变化与注意事项

一、理解定位转变：从库到框架

在独立 dva 项目中，dva 扮演的是轻量级状态流框架与轻度胶水层的角色。开发者通常需要自建打包流程（基于 webpack 或 roadhog），并在项目入口文件（如 src/index.js）中显式维护 dva 实例的完整生命周期：创建应用、按顺序引入并注册每一个 Model、挂载路由器，最后调用 app.start('#root') 完成 DOM 渲染。

而在 Umi 体系中，定位转变为企业级一体化应用框架。dva 被抽象为 Umi 官方插件（@umijs/plugin-dva 或 Umi 内置插件），成为整体技术栈的内在支撑。框架从编译期到运行时全权托管了应用入口、插件装配、路由映射与状态树挂载，开发者只需要关注 Model 的业务逻辑定义与页面消费。

二、核心集成变化盘点

深入理解以下五大集成维度的转变，是保证迁移过程中代码不丢、逻辑不乱的前提。

1. 应用入口与启动流程接管

在独立 dva 项目中，典型的 index.js 入口样板代码如下：

// 独立 dva 典型入口 index.js
import dva from 'dva';
import createLoading from 'dva-loading';
import { createBrowserHistory } from 'history';

const app = dva({ history: createBrowserHistory() });
app.use(createLoading());
app.model(require('./models/global').default);
app.model(require('./models/user').default);
app.router(require('./router').default);
app.start('#root');

在 Umi 中，上述代码被完全消除。Umi 自身包含构建入口与 HTML 挂载机制，开发者不再需要实例化 dva()，更不需要手动调用 app.start()。入口生命周期的自动化不仅削减了大量无意义的样板代码，还彻底解决了 Model 注册顺序不当引发的初始化竞态问题。

2. Model 约定式自动注册

在独立 dva 中，每新增一个 Model，都必须在入口处手动调用一次 app.model()，或者编写动态加载函数。而在 Umi 中，只要文件放置在约定目录下，框架在编译时和运行时就会自动搜集并注册：

• 全局 Model：存放在 src/models/*.ts 或 src/models/*.js，应用启动时直接挂载到根 Store，全应用共享。
• 页面局部 Model：存放在具体页面目录下（例如 src/pages/dashboard/models/*.ts），在访问对应路由分支时按需挂载。

3. 路由与 dva 绑定的解耦

独立 dva 将路由组件与数据流强耦合在 app.router() 回调函数中。而 Umi 将路由配置提升为框架的一级能力，既可以通过 .umirc.ts（或 config/routes.ts）配置静态路由表，也可以采用文件目录约定路由。业务页面只需通过 connect 或 React-Redux 的 Hooks（如 useSelector）订阅所需状态即可，两者之间完全解耦。

4. 统一的 API 导入规范

由于 Umi 采用了插件化的运行时导出设计，项目中不再直接依赖 dva 原生包。所有的工具方法与 Hooks 均收敛至 umi：

// 改造前：独立 dva 导入源
import { connect } from 'dva';
import { routerRedux } from 'dva/router';

// 改造后：Umi 统一导入源
import { connect, useDispatch, useSelector, history } from 'umi';

5. dva-loading 与插件能力的内置化

以往为了监听异步 effects 的加载状态，必须额外依赖 dva-loading 并在 app.use() 中注册。Umi 内置集成了 dva-loading，开发者只需在工程配置中声明启用 dva，就可以直接从 Redux 根状态 state.loading 中按命名空间或具体 effect 名称获取 loading 布尔值。

三、迁移实施五步法操作流程

迁移工作应当按部就班分阶段进行，确保每一步都能被明确验证。

步骤一：调整 package.json 依赖与工程基座

首先清理原有遗留依赖，并接入 Umi 框架脚手架。从 package.json 中移除旧有的 dva、dva-loading、roadhog、react-router-dom 等包，并安装 Umi 核心生态：

# 移除旧依赖
npm uninstall dva dva-loading roadhog react-router-dom

# 安装 Umi 及其 dva 插件（以 Umi 4 / 3 常用生态为例）
npm install umi @umijs/plugins -D

随后在项目根目录下新建配置文件 .umirc.ts（或 .umirc.js），开启 dva 插件能力：

// .umirc.ts 基础配置文件
import { defineConfig } from 'umi';

export default defineConfig({
  plugins: ['@umijs/plugins/dist/dva'],
  dva: {
    immer: true, // 推荐开启，允许在 reducer 中直接修改草稿状态
  },
  routes: [
    { path: '/', component: '@/pages/index' },
    { path: '/dashboard', component: '@/pages/dashboard' },
  ],
});

步骤二：重构目录结构并归集 Model

删除历史入口文件 src/index.js 中的初始化代码。将原项目中散落在各个目录下的 Model 文件统一归类到 src/models/ 目录下（或各功能页面的子 models/ 下）。确保每个 Model 文件导出的对象结构符合标准 dva 规范：

// src/models/user.ts
export default {
  namespace: 'user',
  state: {
    id: null,
    name: '',
  },
  reducers: {
    saveUser(state, { payload }) {
      return { ...state, ...payload };
    },
  },
  effects: {
    *fetchCurrent({ payload }, { call, put }) {
      const data = yield call(queryUser, payload);
      yield put({ type: 'saveUser', payload: data });
    },
  },
};

步骤三：转换路由映射与清除历史路由包裹

将原 src/router.js 中由 <Router>、<Switch>、<Route> 组成的 JSX 语法结构，逐一映射转换为 .umirc.ts 中的 routes 数组配置。在 Umi 中，@/pages/... 作为组件引入的基础别名路径，原有的 HashHistory 或 BrowserHistory 切换也可以直接在配置文件中通过 history: { type: 'browser' } 或 history: { type: 'hash' } 声明，无须在业务代码中手写。

步骤四：批量替换组件引入源与消费方式

在所有需要消费状态或派发 action 的 React 组件中，执行全局替换：

• 将 import { connect } from 'dva' 统一变更为 import { connect } from 'umi'。
• 如果原项目使用了 routerRedux.push('/path') 改变路由，在 Umi 中直接改为 import { history } from 'umi'; history.push('/path');。
• 如果是函数式组件，可进一步利用现代 Hooks（useDispatch, useSelector）替代冗长的 connect(mapStateToProps) 高阶组件包裹，大幅降低视图层层级嵌套。

步骤五：启动调试与链路验收

在终端运行 npm run start（对应命令为 umi dev）。打开浏览器开发者工具及 Redux DevTools 插件，按以下顺序验收：

1. 检查 Store 的顶层 State 节点，确认所有定义的 namespace（例如 user, global 等）是否已全部就位。
2. 确认 state.loading 是否存在并包含 global, models, effects 三个状态子对象。
3. 触发一次页面异步请求，观察 Redux DevTools 中 user/fetchCurrent 的 dispatch 记录、loading 从 true 到 false 的切换，以及 state 的更新是否符合预期。

四、迁移关键注意事项与避坑指南

在实际迁移过程中，由于执行环境和约定的变化，通常会遭遇以下典型问题。提前对照排查能节省大量的排错时间。

五、总结

从独立 dva 迁移至 Umi，核心并不是逻辑重构，而是一次前端工程化标准的对齐。通过将零散的手工初始化与装配工作交由 Umi 的约定扫描和插件机制接管，项目不仅彻底清除了历史遗留的样板代码，还获得了现代化的打包工具链、开箱即用的 TypeScript 类型支持以及更清晰的文件组织规范。遵循本篇梳理的五步法操作与避坑清单，可以帮助团队以极低的风险和改造成本完成平稳迁移。