pages has not been registered yet 常见于路由未注册

Question

在使用微前端框架或某些单页应用（SPA）架构时，常出现“pages has not been registered yet”错误，主要原因为页面组件未正确注册到路由系统。该问题多见于动态路由或懒加载场景，当路由配置未及时挂载或页面模块未在主应用中注册时触发。常见于qiankun、UmiJS等框架中，主应用未识别子应用路由表，或页面路径拼写错误、导出方式不当。解决方法包括检查路由配置文件、确保页面组件正确导出并注册、确认生命周期钩子执行顺序，以及子应用路由与主应用沙箱机制的兼容性。

Answer 1

微前端架构中“pages has not been registered yet”错误的深度解析与解决方案

1. 问题现象与初步定位

在使用 qiankun、UmiJS 等微前端框架或单页应用（SPA）架构时，开发者常遇到如下报错：

Error: pages has not been registered yet

该错误通常出现在页面跳转或路由初始化阶段，表现为白屏或控制台报错。其根本原因在于目标页面组件未被正确注册到主应用的路由系统中。

常见触发场景包括：

• 动态路由配置延迟加载
• 子应用未完成生命周期挂载即尝试访问路由
• 页面路径拼写错误或文件导出方式不规范
• 主应用沙箱机制阻断了子应用路由注册

2. 路由注册机制分析

现代前端框架如 React Router、Vue Router 均依赖运行时路由表维护。以 UmiJS 为例，其通过约定式路由自动生成 routes.ts 文件，若文件生成失败或引入顺序错误，则导致页面未注册。

qiankun 框架中，子应用需在 bootstrap、mount 阶段完成自身路由初始化，并通知主应用更新路由映射表。若此流程中断，主应用无法识别子应用页面。

阶段	执行内容	常见问题点
bootstrap	初始化子应用资源	异步加载未完成
mount	挂载 DOM 与路由	mount 执行前触发跳转
unmount	清理路由监听	内存泄漏或重复注册

3. 核心排查路径与调试策略

为系统性解决该问题，建议按以下流程进行排查：

1. 确认页面组件是否通过 export default 正确导出
2. 检查路由配置文件（如 config/routes.ts）路径是否匹配实际目录结构
3. 验证子应用的 registerMicroApps 是否正确配置 activeRule
4. 查看浏览器 Network 面板，确认 JS Bundle 是否完整加载
5. 在 mount 生命周期中添加调试日志，确认执行时机
6. 启用 qiankun 的 singular: false 多实例模式测试隔离性
7. 检查 Webpack 动态 import 语法是否正确（如 import('./pages/Demo')）
8. 审查主应用路由守卫是否拦截了未注册路径
9. 使用 loadMicroApp 手动预加载子应用，验证注册状态
10. 检查 Babel/TS 编译配置是否影响模块导出结构

4. 典型代码示例与修复方案

以下为一个常见的错误实现与修正对比：

// ❌ 错误：命名导出导致无法被路由系统识别
const HomePage = () => <div>Home</div>;
export { HomePage };

// ✅ 正确：默认导出
const HomePage = () => <div>Home</div>;
export default HomePage;

// ✅ 主应用中确保子应用注册时机
useEffect(() => {
  registerMicroApps([
    {
      name: 'app-vue',
      entry: '//localhost:8080',
      container: '#subapp-viewport',
      activeRule: '/app-vue',
    },
  ]);
  start({ prefetch: true }); // 启用预加载提升注册速度
}, []);

5. 微前端沙箱与路由兼容性设计

qiankun 的运行时沙箱可能隔离全局变量（如 window.history 监听），影响子应用路由初始化。可通过以下方式增强兼容性：

• 在子应用中使用 router.basename 设置基础路径
• 避免直接操作 window.location，改用路由 API
• 在 mount 钩子中重新激活 Vue Router 或 React Router 实例
• 使用 import-html-entry 确保 script 执行上下文正确

Mermaid 流程图展示子应用注册与路由挂载时序：

graph TD
    A[主应用启动] --> B{子应用是否已注册?}
    B -- 否 --> C[调用 registerMicroApps]
    B -- 是 --> D[触发路由匹配]
    C --> E[执行 bootstrap]
    E --> F[执行 mount]
    F --> G[子应用渲染并注册路由]
    G --> H[主应用更新路由视图]
    D --> I[正常跳转页面]