dva.js 开发常见报错排查：model 注册失败与 dispatch 无响应

一、dva.js 运行时数据流转与核心架构模型

理解 dva.js 的排查逻辑，首先需要建立清晰的运行时生命周期认知。dva.js 本质上是对 Redux、Redux-Saga 和 React-Router 的轻量封装。应用启动时，通过 app.model() 将业务领域划分的各个状态单元装载进全局内部列表 app._models 中，并在内部构建对应的 Reducer 字典与 Saga 监听协程。

当在 React 组件中调用 dispatch({ type: 'namespace/action', payload }) 时，该 Action 首先进入 Redux 中间件链条；dva 的内部路由逻辑会根据 / 分隔符解析出所属的 namespace 与具体方法名，分别寻址到同步的 Reducer 或异步的 Effect 生成器。若在这一链路的任何一环出现命名空间丢失、导出格式不匹配或异步协程中断，整个状态变更流就会立即中断。

在图 1 所示的数据流闭环中，故障点 A 至 E 分布于注册、寻址、协程执行与不可变状态落盘等阶段。下文将按故障类别分类展开详尽的排查指南。

二、场景一：Model 注册失败排查路径与解决方案

Model 注册失败通常发生在应用初始化阶段或按需动态加载（Code Splitting）路由切换时。根据浏览器控制台的报错表现，主要可划分为命名空间冲突、对象格式解析失效及约定式目录加载丢失三种典型场景。

1. 报错特征一：[app.model] namespace should be unique

根因机制：dva 内部维护了一个唯一的 Model 集合。当调用 app.model(model) 时，dva 会执行 checkModel(model, app._models)，一旦发现全局已有相同 namespace 的模型存在，便会主动抛出抛错并中断流程。该问题主要源于两类场景：一是两个文件被开发者无意中赋予了相同的 namespace 字符串；二是前端路由按需动态加载时，多次进入同一页面重复执行了 app.model() 且未做防重判断；此外，在 Webpack 模块热替换（HMR）过程中，代码重新编译也常引发重复注入。

解决方案：在动态按需加载或手动注册时，必须加入注册守卫（Registry Guard）或在模块卸载时执行清理：

// 方案 A：基于 _models 列表做幂等性判断（推荐）
function registerModelIfNotExists(app, model) {
  const hasRegistered = app._models.some(m => m.namespace === model.namespace);
  if (!hasRegistered) {
    app.model(model);
  }
}

// 方案 B：在组件或路由卸载钩子中显式调用 unmodel
// 注意：unmodel 会同时清理对应的 reducer 与 saga 监听
export function unloadModel(app, namespace) {
  if (app.unmodel) {
    app.unmodel(namespace);
  }
}

2. 报错特征二：[app.model] model should be object with namespace 或 undefined namespace

根因机制：此报错表明传入 app.model() 的实参并非预期的 Model 配置对象。常见原因在于 ESModule 与 CommonJS 混用导致的 default 包装层未解包。当使用 Babel 转译或在动态 require('./model') 时，导出对象实际上被放置在 { default: { namespace: '...', ... } } 中，若直接传入该包装对象或传入了 undefined，dva 校验 isPlainObject(model) && model.namespace 即会直接失败。

解决方案：统一模块规范，并在动态引入时做解构回退处理：

// 动态加载时兼容 ESModule default 与 CommonJS
const rawModule = require('./models/user');
const userModel = rawModule.default || rawModule;

if (userModel && userModel.namespace) {
  registerModelIfNotExists(app, userModel);
} else {
  console.error('[dva registry error] 模块未包含合法 namespace 配置:', rawModule);
}

3. 报错特征三：无控制台报错，但在 State 中找不到目标 Model

根因机制：多发生于使用 UmiJS 或配置了 dva-loading 的约定式工程中。Umi 默认会自动扫描 src/models 目录下的所有文件以及各页面子目录中的 model.ts/js。如果文件名命名不合规（例如以点 .、下划线 _ 开头，或后缀名不在识别列表内），Umi 构建扫描器会静默忽略该文件，导致看似代码编写完整，但运行期根本没有注入。

排查与修复步骤：

• 检查文件命名规范：确保 Model 放置在 src/models/user.ts 或 src/pages/user/model.ts，不可命名为 _user.ts 或 user.test.ts。
• 排除语法与类型死锁：如果 Model 内部存在顶级运行异常（例如在顶层直接读取了不存在的 window.GLOBAL_DATA.user），在文件被解析阶段就会中断，使得导出无法被加载器捕获。
• 控制台快速验证：打开浏览器开发者工具 Console，输入 window.g_app._models.map(m => m.namespace)，立即核对当前所有已加载的模型命名空间清单。

三、场景二：dispatch 发起无响应排查路径与解决方案

在业务开发中，开发者在组件中编写了 dispatch({ type: '...' })，页面界面和数据没有任何响应，且控制台未打印任何红字。这种“静默失效”往往令人难以着手。沿着数据流转过程，以下是四大最核心的根因。

1. 原因一：Action Type 格式错误与跨 Model 命名空间丢失

根因机制：dva 对 Action 的路由寻址规则具有严格的约定：

• 在 React 视图组件中派发时，必须显式指定完整命名空间前缀，格式为 `${namespace}/${actionName}`（例如 dispatch({ type: 'user/fetch' })）。
• 在 Effect 内部使用 yield put() 触发当前同一个 Model 的 Reducer 或 Effect 时，可以省略命名空间前缀（例如 yield put({ type: 'save' })）；但若跨 Model 派发，则必须加上目标命名空间（例如 yield put({ type: 'app/showLoading' })）。

若在视图组件中写成了 dispatch({ type: 'fetch' })，dva 在 Redux 中间件中无法匹配到任何带有该 Action 的 Reducer 或 Effect，该 Action 会在管道流转完毕后被默默丢弃，不会触发任何报错。

// 错误写法：组件中未加 namespace，dva 无法寻址
dispatch({ type: 'fetchUserList', payload: { page: 1 } }); // 静默失效！

// 正确写法：组件中明确指定目标 Model
dispatch({ type: 'user/fetchUserList', payload: { page: 1 } });

// 在 Model 内部的正确写法对比：
export default {
  namespace: 'user',
  state: { list: [] },
  effects: {
    *fetchUserList({ payload }, { call, put }) {
      const data = yield call(queryUsers, payload);
      // 内部调用当前 model 的 reducer：无需加 user/
      yield put({ type: 'saveList', payload: data });
      // 跨 model 调用全局通知：必须加 app/
      yield put({ type: 'app/showNotification', payload: '加载成功' });
    }
  },
  reducers: {
    saveList(state, { payload }) {
      return { ...state, list: payload };
    }
  }
};

2. 原因二：Effect Generator 函数遗漏星号 * 或缺失 yield

根因机制：dva 的 effects 底层完全由 redux-saga 驱动。每一个 Effect 方法都必须是 Generator 生成器函数。初学者经常容易写成普通函数或 async/await 函数；此外，在调用 put 或 call 时若漏掉了 yield 关键字，会导致 Saga 拦截器无法拿到 Effect Descriptor，整个异步流中断或静默脱轨。

// 典型错误范例：漏星号、漏 yield、使用 await
effects: {
  // 错误 1: 缺少星号，写成普通函数
  fetchList(action, { call, put }) {
    const res = call(fetchApi); // 错误：未执行
    put({ type: 'save', payload: res }); // 错误：不会派发
  },

  // 正确写法：严格声明为 Generator 并对每个 Saga 操作添加 yield
  *fetchList({ payload }, { call, put }) {
    try {
      const res = yield call(fetchApi, payload);
      yield put({ type: 'save', payload: res });
    } catch (error) {
      console.error('[Saga Error in *fetchList]:', error);
      // 必须有错误处理，防止异常未捕获导致 Saga 协程挂起
    }
  }
}

3. 原因三：Reducer 未遵循纯函数不可变更新（State Mutation）

根因机制：React-Redux 的 connect 在计算组件是否需要重新渲染时，使用的是浅层引用比较（shallowEqual）。如果开发者在 Reducer 中直接就地修改了当前 state 对象的属性，并把原 state 引用返回，Redux 判定新旧状态引用完全一致（prevProps === nextProps），因此彻底跳过视图重绘。用户在界面上完全看不到数据更新，直观感觉就是“dispatch 无响应”。

reducers: {
  // 错误范例：直接修改 state 引用（In-place Mutation）
  updateUser(state, { payload }) {
    state.userInfo = payload; // 破坏不可变性！
    state.list.push(payload.newItem); // 破坏不可变性！
    return state; // 引用与修改前完全相等，React-Redux 判定无变化，跳过组件渲染！
  },

  // 正确标准范例：返回全新深浅拷贝引用
  updateUser(state, { payload }) {
    return {
      ...state,
      userInfo: { ...payload },
      list: [...state.list, payload.newItem]
    };
  }
}

4. 原因四：React 组件连接被 mapDispatchToProps 覆盖

根因机制：当使用 connect(mapStateToProps, mapDispatchToProps)(Component) 时，如果向第二个参数传递了自定义的普通对象或函数，React-Redux 就不会自动将全局 dispatch 函数作为 prop 注入到组件中。如果开发者自定义了 mapDispatchToProps 却忘记在返回值中暴露 dispatch，或者写错了形参解构，组件内部的 props.dispatch 就会变成 undefined，直接导致调用报错或调用未绑定的空函数。

// 方案 1：不传第二个参数，React-Redux 默认自动注入 dispatch（绝大多数场景推荐）
export default connect((state) => ({
  user: state.user,
  loading: state.loading
}))(UserComponent);

// 在组件中直接使用 props.dispatch
const UserComponent = ({ dispatch, user }) => {
  const handleClick = () => {
    if (typeof dispatch !== 'function') {
      console.error('dispatch 丢失！请检查 connect 配置');
      return;
    }
    dispatch({ type: 'user/fetch' });
  };
  return <button onClick={handleClick}>刷新数据</button>;
};

四、快速诊断手段与排查工具链

除了肉眼排查代码逻辑外，善用 dva.js 与 Redux 的运行期诊断接口可以极大提高定位效率。

1. 控制台实时探针（window.g_app 探查）

在 dva 应用启动后，dva 实例通常会挂载在全局对象 window.g_app（Umi 体系下标准命名）或挂载在应用主入口的 app 变量上。在浏览器开发者工具控制台中执行以下指令：

// 1. 查看已注册的全部 Model 命名空间与定义
window.g_app._models.map(m => ({
  namespace: m.namespace,
  hasReducers: Object.keys(m.reducers || {}),
  hasEffects: Object.keys(m.effects || {})
}));

// 2. 检查当前 Redux 全局 Store 状态树中是否存在目标数据
window.g_app._store.getState();

// 3. 直接在控制台手动执行 dispatch 测试通道联通性
window.g_app._store.dispatch({
  type: 'user/fetch',
  payload: { debug: true }
});

如果通过 window.g_app._store.dispatch 能够在网络面板或控制台中看到接口触发和状态变化，说明 Model 与底层链路完全正常，问题必在React 组件的 connect 映射或事件绑定阶段；反之如果控制台手动派发依然毫无反应，则问题锁定在Action Type 拼写错误、Model 未注册或 Effect 编写格式错误。

2. 配置全局 onError 捕获静默异常

Redux-Saga 的一个常见特性是：如果在 Effect 内部执行某些方法抛出了语法错误、网络未捕获错误或空指针异常，且没有配置全局的异常捕获中间件，整个 Saga 可能会被取消并处于静默挂起状态。必须在应用初始化时注入 onError 钩子：

import dva from 'dva';
import { message } from 'antd';

const app = dva({
  onError(e, dispatch) {
    // 捕获未处理的 effect 与 reducer 异常
    console.error('[dva 全局异常拦截]', e);
    message.error(e.message || '系统运行异常，请查看控制台日志');
  },
});

// 在 UmiJS 工程中，可在 src/app.ts 中配置：
export const dvaConfig = {
  config: {
    onError(err: any) {
      console.error('[Umi dva onError]:', err);
    },
  },
};

五、总结与工程化防御规范

为了杜绝在后续业务迭代中反复出现 Model 注册失败和 dispatch 无响应，团队在日常工程实践中应遵循以下防御性规范：

1. 统一文件与 Namespace 命名契约：保持 Model 文件路径与 namespace 严格一致。例如 src/models/userProfile.ts 的 namespace 必须声明为 userProfile，严禁跨模块复制粘贴时遗留历史名称。
2. 使用常量或 TypeScript 枚举定义 Action：避免手写脆弱的硬编码字符串，借助 TypeScript 类型推导防止因拼写错误引起的 Action 丢失。
3. 规范动态注入流程：在路由按需加载时，封装统一的 safeRegisterModel(app, model) 辅助函数，内置对 .default 的自动提取与 _models 的防重检测。
4. 坚守纯函数 Reducer 与标准 Generator 规范：编写 Reducer 时借助 Object Spread 或 Immer 确保深浅拷贝不可变性；编写 Effect 时严格使用 function* 并对每个副作用操作显式添加 yield。