generator-mico-cli 0.2.2 → 0.2.5

package/generators/micro-react/templates/apps/layout/docs/feature-/345/276/256/345/211/215/347/253/257/346/250/241/345/274/217.md

@@ -1,6 +1,7 @@
 # 微前端模式
 
 > 创建时间：2025-12-26
+> 更新时间：2025-01-25（加载健壮性增强）
 
 ## 功能概述
 
@@ -27,14 +28,16 @@
 
 ### 核心文件
 
-| 文件路径                                   | 说明                       |
-| ------------------------------------------ | -------------------------- |
-| `src/components/MicroAppLoader/index.tsx`  | qiankun 微应用加载器组件   |
-| `src/components/MicroAppLoader/index.less` | 加载器样式                 |
-| `src/common/menu/parser.ts`                | 菜单解析，包含加载类型判断 |
-| `src/common/menu/types.ts`                 | 类型定义                   |
-| `src/layouts/index.tsx`                    | 主布局，集成微应用渲染     |
-| `config/config.ts`                         | qiankun master 配置        |
+| 文件路径                                            | 说明                             |
+| --------------------------------------------------- | -------------------------------- |
+| `src/components/MicroAppLoader/index.tsx`           | qiankun 微应用加载器组件         |
+| `src/components/MicroAppLoader/container-manager.ts`| 容器生命周期管理、会话 ID 机制   |
+| `src/components/MicroAppLoader/index.less`          | 加载器样式                       |
+| `src/common/menu/parser.ts`                         | 菜单解析，包含加载类型判断       |
+| `src/common/menu/types.ts`                          | 类型定义                         |
+| `src/layouts/index.tsx`                             | 主布局，集成微应用渲染           |
+| `src/app.tsx`                                       | qiankun 全局错误处理             |
+| `config/config.ts`                                  | qiankun master 配置              |
 
 ## API / 组件接口
 
@@ -430,3 +433,82 @@ export default function HomePage() {
 有 htmlUrl 或 jsUrls  →  microapp (使用 qiankun 加载)
 无 htmlUrl 且无 jsUrls →  internal (使用 Outlet 渲染)
 ```
+
+## 加载健壮性机制
+
+> 更新于 2025-01-25
+
+### 解决的问题
+
+| 原问题 | 风险 | 修复方案 |
+|--------|------|----------|
+| 无全局错误处理，子应用异常可能导致页面崩溃 | 高 | 添加 `addGlobalUncaughtErrorHandler` |
+| unmount 使用 rAF 时序不可靠 | 高 | 使用 `queueMicrotask` |
+| 同名应用并发加载可能冲突 | 高 | 会话 ID 锁 + `waitForUnmount` |
+| unmount 可能永久卡死 | 中 | 10 秒超时机制 |
+| 加载期间 Props 变化被跳过 | 中 | 加载完成后重新同步 Props |
+
+### 全局错误处理
+
+在 `src/app.tsx` 中注册 qiankun 全局错误处理器，捕获子应用运行时未捕获的异常：
+
+```typescript
+import { addGlobalUncaughtErrorHandler } from 'qiankun';
+
+addGlobalUncaughtErrorHandler((event: Event | string) => {
+  // 捕获子应用 JS 运行时错误
+  // 捕获子应用生命周期钩子异常
+  // 捕获资源加载失败
+  console.error('[qiankun] Global uncaught error:', event);
+});
+```
+
+### container-manager API
+
+容器管理器提供会话 ID 机制防止并发加载冲突：
+
+```typescript
+/** 开始加载会话，返回唯一会话 ID */
+function startLoadSession(appName: string): number;
+
+/** 检查会话是否仍然有效（被新加载覆盖时返回 false） */
+function isLoadSessionValid(appName: string, sessionId: number): boolean;
+
+/** 标记加载完成 */
+function markLoadComplete(appName: string, sessionId: number): boolean;
+
+/** 等待当前卸载操作完成（如果有） */
+async function waitForUnmount(appName: string): Promise<void>;
+
+/** 获取当前加载状态 */
+function getLoadingStatus(appName: string): 'idle' | 'loading' | 'mounted' | 'unmounting';
+```
+
+### 快速切换时序
+
+```
+场景：A → B → A 快速切换
+
+A1 开始加载 (sessionId=1)
+  ↓
+切换到 B，A1 cleanup 在 queueMicrotask 中执行
+  ↓
+切换回 A，A2 开始加载 (sessionId=2)
+  ↓
+A2 调用 waitForUnmount()，等待 A1 完全卸载
+  ↓
+A1 卸载完成（带 10 秒超时保护）
+  ↓
+A2 继续加载，每个异步步骤检查 isLoadSessionValid(sessionId)
+  ↓
+加载完成后立即同步最新 Props（locale/timezone 等）
+```
+
+### 设计决策
+
+| 决策点 | 选择 | 理由 |
+|--------|------|------|
+| 卸载时机 | `queueMicrotask` | 在当前事件循环末尾执行，比 `requestAnimationFrame` 更快更可靠 |
+| 并发控制 | 会话 ID 机制 | 简单高效，无需复杂的锁机制 |
+| 超时时间 | 10 秒 | 平衡等待时间与异常检测速度 |
+| Props 同步 | 加载后立即同步 | 确保加载期间的变化不丢失 |

package/generators/micro-react/templates/apps/layout/src/app.tsx

@@ -55,11 +55,14 @@ if (typeof window !== 'undefined') {
     });
 
     // 检查是否是子应用加载失败（资源 404 等）
+    // 只匹配明确的关键词，避免误判业务错误（如 "upload failed"）
     const isLoadError =
       errorMessage.includes('Failed to fetch') ||
       errorMessage.includes('Loading chunk') ||
-      errorMessage.includes('load') ||
-      errorMessage.includes('Script error');
+      errorMessage.includes('ChunkLoadError') ||
+      errorMessage.includes('Script error') ||
+      errorMessage.includes('Loading CSS chunk') ||
+      (event instanceof ErrorEvent && event.type === 'error');
 
     if (isLoadError) {
       console.error(
@@ -72,73 +75,6 @@ if (typeof window !== 'undefined') {
   });
 }
 
-// ==================== 微应用预加载 ====================
-// 预加载所有微应用资源，避免快速切换时的竞态条件
-// 当资源已预加载时，loadMicroApp 的异步加载会快速完成，减少容器不存在的错误
-
-/**
- * 是否启用微应用预加载
- * - 可通过 URL 参数 ?prefetch=false 禁用（方便调试加载时序问题）
- * - 可通过 localStorage.setItem('DISABLE_MICRO_APP_PREFETCH', 'true') 禁用
- * - 默认启用
- */
-const isPrefetchEnabled = (): boolean => {
-  if (typeof window === 'undefined') return false;
-
-  // URL 参数优先级最高
-  const urlParams = new URLSearchParams(window.location.search);
-  const prefetchParam = urlParams.get('prefetch');
-  if (prefetchParam === 'false') {
-    console.log('[App] Prefetch disabled via URL parameter');
-    return false;
-  }
-
-  // localStorage 开关
-  if (localStorage.getItem('DISABLE_MICRO_APP_PREFETCH') === 'true') {
-    console.log('[App] Prefetch disabled via localStorage');
-    return false;
-  }
-
-  return true;
-};
-
-const prefetchMicroApps = () => {
-  if (!isPrefetchEnabled()) {
-    return;
-  }
-
-  try {
-    const menus = getWindowMenus();
-    const routes = extractRoutes(menus);
-
-    // 筛选出所有微应用路由
-    const microApps = routes
-      .filter((route) => route.loadType === 'microapp' && route.entry)
-      .map((route) => ({
-        name: route.path,
-        entry: route.entry!,
-      }));
-
-    if (microApps.length > 0) {
-      console.log('[App] Prefetching micro apps:', microApps);
-      prefetchApps(microApps);
-    }
-  } catch (error) {
-    console.warn('[App] Failed to prefetch micro apps:', error);
-  }
-};
-
-// 在页面加载后预加载微应用
-if (typeof window !== 'undefined') {
-  // 使用 requestIdleCallback 在浏览器空闲时预加载，避免影响首屏渲染
-  if ('requestIdleCallback' in window) {
-    window.requestIdleCallback(() => prefetchMicroApps(), { timeout: 3000 });
-  } else {
-    // 降级方案：延迟 1 秒后预加载
-    setTimeout(prefetchMicroApps, 1000);
-  }
-}
-
 // ==================== 微前端共享依赖 ====================
 // 将公共库暴露到 window，供子应用复用，避免重复打包
 // 子应用通过 externals 配置引用这些全局变量

package/generators/micro-react/templates/apps/layout/src/common/micro/index.ts

@@ -32,6 +32,40 @@ export type {
   MicroAppErrorSource,
 } from './types';
 
+
+// ============================================
+// 微应用名称生成
+// ============================================
+
+/**
+ * 从 entry URL 中提取微应用标识
+ * 同一个 entry 的所有路由使用相同的标识，避免频繁卸载/重载微应用
+ *
+ * 注意：使用完整的 origin + pathname 作为标识，避免同一 host 上多个子应用冲突
+ * 例如：http://localhost:8010/app1/ 和 http://localhost:8010/app2/ 会有不同的标识
+ *
+ * @param entry 微应用入口 URL
+ * @returns 微应用标识（字母数字和连字符组成）
+ */
+export const getAppNameFromEntry = (entry: string): string => {
+  try {
+    const url = new URL(entry, window.location.href);
+    // 使用 origin + pathname 作为标识，确保不同路径的子应用有不同标识
+    // 如 "localhost-8010" 或 "localhost-8010-app1"
+    const identifier = url.host + url.pathname;
+    return identifier
+      .replace(/[^a-zA-Z0-9]/g, '-')
+      .replace(/-+/g, '-')
+      .replace(/^-|-$/g, '');
+  } catch {
+    // fallback：使用 entry 的 hash
+    return entry
+      .replace(/[^a-zA-Z0-9]/g, '-')
+      .replace(/-+/g, '-')
+      .replace(/^-|-$/g, '');
+  }
+};
+
 // ============================================
 // 环境检测
 // ============================================

package/generators/micro-react/templates/apps/layout/src/common/micro-prefetch.ts

@@ -0,0 +1,108 @@
+/**
+ * 微应用预加载管理
+ *
+ * 策略：当前子应用挂载成功后，再逐个预加载其他子应用
+ * 避免与当前加载的子应用竞争网络带宽
+ */
+
+import { prefetchApps } from 'qiankun';
+import { extractRoutes, getWindowMenus } from './menu';
+import { getAppNameFromEntry } from './micro';
+
+/**
+ * 是否启用微应用预加载
+ * - 可通过 URL 参数 ?prefetch=false 禁用（方便调试加载时序问题）
+ * - 可通过 localStorage.setItem('DISABLE_MICRO_APP_PREFETCH', 'true') 禁用
+ * - 默认启用
+ */
+export const isPrefetchEnabled = (): boolean => {
+  if (typeof window === 'undefined') return false;
+
+  // URL 参数优先级最高
+  const urlParams = new URLSearchParams(window.location.search);
+  const prefetchParam = urlParams.get('prefetch');
+  if (prefetchParam === 'false') {
+    console.log('[Prefetch] Disabled via URL parameter');
+    return false;
+  }
+
+  // localStorage 开关
+  if (localStorage.getItem('DISABLE_MICRO_APP_PREFETCH') === 'true') {
+    console.log('[Prefetch] Disabled via localStorage');
+    return false;
+  }
+
+  return true;
+};
+
+/** 已预加载的应用 entry 集合 */
+const prefetchedApps = new Set<string>();
+
+/**
+ * 获取所有需要预加载的微应用（排除已预加载的）
+ */
+export const getMicroAppsForPrefetch = (
+  excludeEntry?: string,
+): Array<{ name: string; entry: string }> => {
+  try {
+    const menus = getWindowMenus();
+    const routes = extractRoutes(menus);
+
+    return routes
+      .filter(
+        (route) =>
+          route.loadType === 'microapp' &&
+          route.entry &&
+          route.entry !== excludeEntry &&
+          !prefetchedApps.has(route.entry),
+      )
+      .map((route) => ({
+        name: getAppNameFromEntry(route.entry!),
+        entry: route.entry!,
+      }));
+  } catch (error) {
+    console.warn('[Prefetch] Failed to get micro apps:', error);
+    return [];
+  }
+};
+
+/**
+ * 预加载微应用（低优先级，在浏览器空闲时并发预加载）
+ * @param currentEntry 当前正在加载的应用 entry，会被排除
+ */
+export const prefetchMicroAppsLowPriority = (currentEntry?: string): void => {
+  if (!isPrefetchEnabled()) {
+    return;
+  }
+
+  const apps = getMicroAppsForPrefetch(currentEntry);
+  if (apps.length === 0) {
+    return;
+  }
+
+  // 标记为已预加载，避免重复
+  apps.forEach((app) => prefetchedApps.add(app.entry));
+
+  console.log(
+    '[Prefetch] Will prefetch micro apps:',
+    apps.map((a) => a.name),
+  );
+
+  // 使用 requestIdleCallback 确保在浏览器空闲时执行，不阻塞当前渲染
+  const doPrefetch = () => {
+    prefetchApps(apps); // qiankun 会并发预加载所有应用
+  };
+
+  if ('requestIdleCallback' in window) {
+    window.requestIdleCallback(doPrefetch, { timeout: 5000 });
+  } else {
+    setTimeout(doPrefetch, 100);
+  }
+};
+
+/**
+ * 标记应用已加载（避免重复预加载）
+ */
+export const markAppAsPrefetched = (entry: string): void => {
+  prefetchedApps.add(entry);
+};

package/generators/micro-react/templates/apps/layout/src/common/request/index.ts

@@ -16,7 +16,7 @@
 
 import { request as rawRequest } from '@umijs/max';
 import { setStoredAuthToken } from '../auth/auth-manager';
-import { ROUTES } from '../constants';
+import { NO_AUTH_ROUTE_LIST } from '@/constants';
 
 // 配置相关
 import {
@@ -64,7 +64,7 @@ initDefaultInterceptors(isFetchingToken, addToPendingQueue);
  * 判断当前路由是否跳过认证
  */
 const shouldSkipAuth = (): boolean => {
-  return ROUTES.NO_AUTH_ROUTES.includes(location.pathname);
+  return NO_AUTH_ROUTE_LIST.includes(location.pathname);
 };
 
 /**