@bm-fe/react-native-multi-bundle 1.0.0-beta.0

package/src/multi-bundle/DevModeConfig.ts

@@ -0,0 +1,23 @@
+/**
+ * DevModeConfig - 开发模式配置
+ * 
+ * HTTP 模式：使用 ModuleLoaderMock，通过 HTTP 加载 bundle
+ */
+
+export type DevMode = 'http';
+
+/**
+ * 获取当前开发模式
+ * 始终返回 'http'（HTTP 模式）
+ */
+export function getDevMode(): DevMode {
+  return 'http';
+}
+
+/**
+ * 检查是否使用 HTTP 模式（ModuleLoaderMock）
+ */
+export function useHttpMode(): boolean {
+  return true;
+}
+

package/src/multi-bundle/HMRClient.ts

@@ -0,0 +1,157 @@
+import { Platform } from 'react-native';
+
+/**
+ * 自定义 HMR Client
+ * 用于监听 Metro 的 /hot 端点，实现多 Bundle 的热更新
+ */
+export class HMRClient {
+  private static instance: HMRClient;
+  private ws: WebSocket | null = null;
+  private host: string = 'localhost';
+  private port: number = 8081;
+  private isEnabled: boolean = false;
+  private pendingEntryPoints: string[] = [];
+
+  private constructor() {}
+
+  public static getInstance(): HMRClient {
+    if (!HMRClient.instance) {
+      HMRClient.instance = new HMRClient();
+    }
+    return HMRClient.instance;
+  }
+
+  /**
+   * 初始化并连接 WebSocket
+   */
+  public setup(host: string, port: number) {
+    if (this.isEnabled) return;
+    
+    this.host = host;
+    this.port = port;
+    this.isEnabled = true;
+    
+    this.connect();
+  }
+
+  private connect() {
+    if (!this.isEnabled) return;
+
+    const url = `ws://${this.host}:${this.port}/hot`;
+    console.log('[HMRClient] Connecting to:', url);
+
+    this.ws = new WebSocket(url);
+
+    this.ws.onopen = () => {
+      console.log('[HMRClient] Connected');
+      this.flushEntryPoints();
+    };
+
+    this.ws.onmessage = (event) => {
+      try {
+        const data = JSON.parse(event.data as string);
+        this.processMessage(data);
+      } catch (e) {
+        console.error('[HMRClient] Failed to parse message:', e);
+      }
+    };
+
+    this.ws.onerror = (e) => {
+      console.log('[HMRClient] Connection error:', (e as any).message);
+    };
+
+    this.ws.onclose = () => {
+      console.log('[HMRClient] Disconnected');
+      this.ws = null;
+      // 尝试重连
+      if (this.isEnabled) {
+        setTimeout(() => this.connect(), 2000);
+      }
+    };
+  }
+
+  /**
+   * 注册 Bundle 入口
+   * 当 Bundle 加载时调用，告诉 Metro 我们关心这个 Bundle 的更新
+   */
+  public registerBundle(bundleUrl: string) {
+    if (!__DEV__) return;
+    
+    // 避免重复注册
+    if (!this.pendingEntryPoints.includes(bundleUrl)) {
+      this.pendingEntryPoints.push(bundleUrl);
+      this.flushEntryPoints();
+    }
+  }
+
+  private flushEntryPoints() {
+    if (!this.ws || this.ws.readyState !== WebSocket.OPEN || this.pendingEntryPoints.length === 0) {
+      return;
+    }
+
+    const message = {
+      type: 'register-entrypoints',
+      entryPoints: this.pendingEntryPoints,
+    };
+
+    this.ws.send(JSON.stringify(message));
+    // 注意：不要清空 pendingEntryPoints，因为断线重连后需要重新注册
+  }
+
+  private processMessage(message: any) {
+    if (message.type === 'update') {
+      console.log('[HMRClient] Received update');
+      this.applyUpdate(message.body);
+    } else if (message.type === 'update-start') {
+      console.log('[HMRClient] Update start');
+    } else if (message.type === 'update-done') {
+      console.log('[HMRClient] Update done');
+    } else if (message.type === 'error') {
+      console.error('[HMRClient] Metro error:', message.body);
+    }
+  }
+
+  private applyUpdate(body: any) {
+    const { modified, added, deleted } = body;
+
+    if (modified && modified.length > 0) {
+      modified.forEach((mod: any) => {
+        const [moduleId, moduleCode] = mod.module;
+        // console.log(`[HMRClient] Applying update for module: ${moduleId}`);
+        
+        try {
+          // 执行新的模块代码
+          // 模块代码通常包含 __d(...) 调用
+          // 我们使用 Function 构造函数或 eval 来执行它
+          
+          // 如果 moduleCode 已经是字符串形式的代码
+          // 注意：Metro HMR 发送的代码可能需要处理
+          
+          // 在 React Native 环境中，__d 是全局函数
+          // 直接执行代码应该会更新模块定义
+          
+          // 使用 Function 更加安全，但需要确保作用域正确
+          // 这里简单使用 indirect eval
+          (0, eval)(moduleCode);
+          
+          // 强制刷新引用了该模块的组件？
+          // 如果 React Fast Refresh 启用，它应该会自动处理
+          // 但我们需要确保 Metro 的 runtime 能够感知到模块变化
+          
+          // HACK: 触发一个全局事件或者直接调用 RN 的刷新机制
+          // 但由于我们是自定义加载，可能需要手动触发重新渲染
+        } catch (error) {
+          console.error(`[HMRClient] Failed to apply update for module ${moduleId}:`, error);
+        }
+      });
+    }
+  }
+
+  public disable() {
+    this.isEnabled = false;
+    if (this.ws) {
+      this.ws.close();
+      this.ws = null;
+    }
+  }
+}

package/src/multi-bundle/LocalBundleManager.ts

@@ -0,0 +1,155 @@
+/**
+ * LocalBundleManager - Bundle 管理接口封装
+ * - 开发环境：从开发服务器获取 manifest（HTTP 模式）
+ * - 生产环境：从 Native CodePush 模块获取 manifest（直接返回 JSON 对象）
+ */
+
+import { BundleManifest } from './ModuleRegistry';
+import { Platform, NativeModules } from 'react-native';
+import { getDevMode, type DevMode } from './DevModeConfig';
+import { getGlobalConfig } from './config';
+
+/**
+ * 获取当前激活包的根目录
+ * HTTP 模式：返回空字符串（不需要 root path）
+ */
+async function getCurrentPackageRootPath(): Promise<string> {
+  // HTTP 模式：不需要 root path
+  return '';
+}
+
+/**
+ * 将 Native 返回的 WritableMap 转换为 BundleManifest
+ */
+function convertNativeManifestToBundleManifest(nativeManifest: any): BundleManifest {
+  // Native 可能返回字符串或对象，需要先处理
+  let manifestObj: any;
+  
+  if (typeof nativeManifest === 'string') {
+    // 如果是字符串，先解析为 JSON 对象
+    try {
+      manifestObj = JSON.parse(nativeManifest);
+    } catch (error) {
+      console.error('[LocalBundleManager] Failed to parse native manifest string:', error);
+      throw new Error('Invalid manifest format: failed to parse JSON string');
+    }
+  } else {
+    // 如果已经是对象，直接使用
+    manifestObj = nativeManifest;
+  }
+  
+  return {
+    formatVersion: manifestObj.formatVersion || 1,
+    main: {
+      file: manifestObj.main?.file || '',
+      version: manifestObj.main?.version || '1.0.0',
+    },
+    modules: (manifestObj.modules || []).map((m: any) => ({
+      id: m.id,
+      file: m.file,
+      version: m.version || '1.0.0',
+      dependencies: m.dependencies || [],
+      lazy: m.lazy !== false,
+    })),
+  };
+}
+
+/**
+ * 获取当前激活包的 manifest
+ * - 开发环境：从开发服务器获取 manifest（HTTP 模式）
+ * - 生产环境：从 Native CodePush 模块获取 manifest（直接返回 JSON 对象）
+ */
+async function getCurrentBundleManifest(): Promise<BundleManifest> {
+  // 生产环境：从 Native 模块获取 manifest
+  if (!__DEV__) {
+    try {
+      const nativeManifest = await NativeModules.CodePush.getCurrentBundleManifestContent();
+      if (nativeManifest) {
+        return convertNativeManifestToBundleManifest(nativeManifest);
+      } else {
+        // Native 模块返回 null 或 undefined
+        throw new Error(
+          '[LocalBundleManager] Native module returned null manifest. ' +
+          'Please ensure bundle-manifest.json exists in the app bundle.'
+        );
+      }
+    } catch (error) {
+      console.error(
+        `[LocalBundleManager] Failed to get manifest from Native: ${error}`
+      );
+      // 生产环境无法获取 manifest 时抛出异常
+      throw new Error(
+        `[LocalBundleManager] Failed to get manifest from Native module: ${error}`
+      );
+    }
+  }
+
+  // 开发环境：从开发服务器获取 manifest
+  const config = getGlobalConfig();
+  const devServer = config?.devServer;
+  
+  if (devServer) {
+    try {
+      const protocol = devServer.protocol || 'http';
+      const platform = Platform.OS;
+      const manifestUrl = `${protocol}://${devServer.host}:${devServer.port}/bundle-manifest.json?platform=${platform}`;
+      const response = await fetch(manifestUrl);
+      if (response.ok) {
+        const manifest: BundleManifest = await response.json();
+        return manifest;
+      } else {
+        console.warn(
+          `[LocalBundleManager] Failed to fetch manifest: HTTP ${response.status} ${response.statusText}`
+        );
+      }
+    } catch (error) {
+      console.warn(
+        `[LocalBundleManager] Failed to fetch manifest from dev server: ${error}`
+      );
+    }
+  } else {
+    // 降级到默认配置（向后兼容）
+    try {
+      const host = Platform.OS === 'android' ? '10.0.2.2' : 'localhost';
+      const platform = Platform.OS;
+      const manifestUrl = `http://${host}:8081/bundle-manifest.json?platform=${platform}`;
+      const response = await fetch(manifestUrl);
+      if (response.ok) {
+        const manifest: BundleManifest = await response.json();
+        return manifest;
+      } else {
+        console.warn(
+          `[LocalBundleManager] Failed to fetch manifest: HTTP ${response.status} ${response.statusText}`
+        );
+      }
+    } catch (error) {
+      console.warn(
+        `[LocalBundleManager] Failed to fetch manifest from dev server: ${error}`
+      );
+    }
+  }
+
+  // 所有尝试都失败，抛出异常
+  throw new Error(
+    '[LocalBundleManager] Failed to get bundle manifest: ' +
+    'Unable to fetch manifest from dev server or Native module. ' +
+    'Please ensure Metro server is running and bundle-manifest.json is accessible.'
+  );
+}
+
+
+
+/**
+ * 获取当前开发模式
+ */
+function getCurrentDevMode(): DevMode {
+  return getDevMode();
+}
+
+
+export const LocalBundleManager = {
+  getCurrentPackageRootPath,
+  getCurrentBundleManifest,
+  getCurrentDevMode,
+};
+

package/src/multi-bundle/ModuleErrorFallback.tsx

@@ -0,0 +1,85 @@
+/**
+ * ModuleErrorFallback - 模块加载失败的兜底组件
+ */
+
+import React from 'react';
+import { View, Text, TouchableOpacity, StyleSheet } from 'react-native';
+
+interface Props {
+  moduleId: string;
+  error: Error | null;
+  onRetry: () => void;
+  onGoHome?: () => void;
+}
+
+export function ModuleErrorFallback({
+  moduleId,
+  error,
+  onRetry,
+  onGoHome,
+}: Props) {
+  return (
+    <View style={styles.container}>
+      <Text style={styles.title}>{moduleId} 模块暂时无法使用</Text>
+      {error && (
+        <Text style={styles.errorText} selectable>
+          {error.message || String(error)}
+        </Text>
+      )}
+      <View style={styles.buttonContainer}>
+        <TouchableOpacity style={styles.button} onPress={onRetry}>
+          <Text style={styles.buttonText}>重试</Text>
+        </TouchableOpacity>
+        {onGoHome && (
+          <TouchableOpacity style={styles.button} onPress={onGoHome}>
+            <Text style={styles.buttonText}>返回首页</Text>
+          </TouchableOpacity>
+        )}
+      </View>
+    </View>
+  );
+}
+
+const styles = StyleSheet.create({
+  container: {
+    flex: 1,
+    justifyContent: 'center',
+    alignItems: 'center',
+    backgroundColor: '#fff',
+    padding: 20,
+  },
+  title: {
+    fontSize: 20,
+    fontWeight: 'bold',
+    color: '#333',
+    marginBottom: 16,
+    textAlign: 'center',
+  },
+  errorText: {
+    fontSize: 14,
+    color: '#d32f2f',
+    marginBottom: 24,
+    textAlign: 'center',
+    padding: 12,
+    backgroundColor: '#ffebee',
+    borderRadius: 4,
+    width: '100%',
+  },
+  buttonContainer: {
+    width: '100%',
+    maxWidth: 300,
+  },
+  button: {
+    backgroundColor: '#007AFF',
+    padding: 15,
+    borderRadius: 8,
+    marginVertical: 8,
+    alignItems: 'center',
+  },
+  buttonText: {
+    color: '#fff',
+    fontSize: 16,
+    fontWeight: '600',
+  },
+});
+

package/src/multi-bundle/ModuleLoaderMock.ts

@@ -0,0 +1,169 @@
+/**
+ * ModuleLoaderMock - Native ModuleLoader 的 Mock 实现
+ * 用于开发环境，模拟 Native 模块加载能力
+ * 
+ * 注意：生产环境需要真实的 Native 实现
+ * 
+ * 在开发环境中，我们通过 Metro bundler 的 HTTP 服务器加载 bundle
+ */
+
+import { Platform } from 'react-native';
+import { HMRClient } from './HMRClient';
+
+interface LoadResult {
+  success: boolean;
+  errorMessage?: string;
+}
+
+
+
+// 已完成的 bundle
+const loadedBundles = new Set<string>();
+// 正在加载中的 bundle（并发复用）
+const inflightBundles = new Map<string, Promise<LoadResult>>();
+
+/**
+ * 根据 bundleId 构建 HTTP URL（开发环境）
+ * 
+ * 在开发环境中，我们通过 Metro bundler 的 HTTP 服务器加载 bundle
+ * 根据 bundleId 直接构建对应的 HTTP URL
+ */
+function buildHttpUrlFromBundleId(bundleId: string): string {
+  const host = Platform.OS === 'android' ? '10.0.2.2' : 'localhost';
+  
+  // 简单的模块 ID 到目录名的映射
+  // 假设模块 ID 为小写，目录名为首字母大写
+  // 例如: home -> Home
+  const moduleName = bundleId.charAt(0).toUpperCase() + bundleId.slice(1);
+  
+  // 构建 Metro 请求 URL
+  // 请求源码入口文件，Metro 会自动打包
+  // 注意：使用 .bundle 后缀，Metro 会识别并构建对应的 .ts/.tsx 文件
+  return `http://${host}:8081/src/modules/${moduleName}/index.bundle` +
+     `?platform=${Platform.OS}` +
+     `&dev=true` +
+     `&minify=false` +
+     `&modulesOnly=true` +      // ✅ 只生成 __d(...)，不带 runtime
+     `&runModule=true`;         // ✅ 不自动执行入口
+}
+
+/**
+ * 加载 bundle 文件（Mock 实现）
+ * 
+ * 在开发环境中，我们通过 HTTP 服务器加载 bundle 并执行
+ * 实际生产环境应该调用 Native CodePush.loadBusinessBundle
+ * 
+ * @param bundleId 模块 ID
+ * @param bundlePath bundle 文件路径（开发环境可能不使用，但为保持接口一致性保留）
+ */
+async function loadBusinessBundle(bundleId: string, bundlePath: string): Promise<LoadResult> {
+  try {
+    // 1. 基本校验
+    if (!bundleId || bundleId.trim() === '') {
+      return {
+        success: false,
+        errorMessage: 'EMPTY_BUNDLE_ID',
+      };
+    }
+
+    if (!__DEV__) {
+      return {
+        success: false,
+        errorMessage:
+          'ModuleLoaderMock should not be used in production. Please implement Native CodePush.loadBusinessBundle.',
+      };
+    }
+
+    // 开发环境：根据 bundleId 构建 HTTP URL
+    const httpUrl = buildHttpUrlFromBundleId(bundleId);
+
+    // 已经加载过的 bundle，不再重复执行
+    if (loadedBundles.has(httpUrl)) {
+      // 确保即使加载过也注册 HMR，处理重新连接或初始化时机问题
+      if (__DEV__) {
+        HMRClient.getInstance().registerBundle(httpUrl);
+      }
+      return { success: true };
+    }
+
+    // 正在加载中，复用同一个 Promise
+    const existing = inflightBundles.get(httpUrl);
+    if (existing) {
+      return existing;
+    }
+
+    const task: Promise<LoadResult> = (async () => {
+      // 从 HTTP 服务器获取 bundle
+      const response = await fetch(httpUrl);
+      if (!response.ok) {
+        // 如果 HTTP 加载失败
+        console.warn(
+          `[ModuleLoaderMock] HTTP load failed (${response.status})`
+        );
+        
+        return { 
+          success: false, 
+          errorMessage: `HTTP_ERROR_${response.status}` 
+        };
+      }
+      
+      const bundleCode = await response.text();
+      
+      // 在 React Native 中执行 bundle 代码
+      try {
+        // 帮 stack trace 标一下来源（部分引擎支持）
+        const wrappedCode = bundleCode.includes('//# sourceURL=')
+          ? bundleCode
+          : `${bundleCode}\n//# sourceURL=${httpUrl}`;
+        // 使用 Function 构造函数执行代码（更安全）
+        const executeCode = new Function(wrappedCode);
+        executeCode();
+        loadedBundles.add(httpUrl);
+        if (__DEV__) {
+          HMRClient.getInstance().registerBundle(httpUrl);
+        }
+        return { success: true };
+      } catch (evalError) {
+        // 如果 Function 构造函数失败，尝试直接 eval（不推荐，但作为后备）
+        console.warn(
+          '[ModuleLoaderMock] Function constructor failed, trying eval'
+        );
+        try {
+          // eslint-disable-next-line no-eval
+          eval(bundleCode);
+          loadedBundles.add(httpUrl);
+          if (__DEV__) {
+            HMRClient.getInstance().registerBundle(httpUrl);
+          }
+          return { success: true };
+        } catch (e) {
+          const msg = e instanceof Error ? e.message : String(e);
+          console.error(`[ModuleLoaderMock] Eval failed: ${msg}`);
+          return { success: false, errorMessage: msg };
+        }
+      }
+    })();
+    inflightBundles.set(httpUrl, task);
+
+    const result = await task;
+    inflightBundles.delete(httpUrl);
+    return result;
+  } catch (error) {
+    const errorMessage =
+      error instanceof Error ? error.message : String(error);
+    console.error(`[ModuleLoaderMock] Load failed: ${errorMessage}`);
+    return {
+      success: false,
+      errorMessage: `EXCEPTION: ${errorMessage}`,
+    };
+  }
+}
+
+export const ModuleLoader = {
+  loadBusinessBundle,
+  // 为了向后兼容，保留 loadBundleFile 别名
+  loadBundleFile: loadBusinessBundle,
+};
+
+export type { LoadResult };
+

package/src/multi-bundle/ModuleLoadingPlaceholder.tsx

@@ -0,0 +1,34 @@
+/**
+ * ModuleLoadingPlaceholder - 模块加载中的占位组件
+ */
+
+import React from 'react';
+import { View, Text, ActivityIndicator, StyleSheet } from 'react-native';
+
+interface Props {
+  moduleId: string;
+}
+
+export function ModuleLoadingPlaceholder({ moduleId }: Props) {
+  return (
+    <View style={styles.container}>
+      <ActivityIndicator size="large" color="#007AFF" />
+      <Text style={styles.text}>正在加载 {moduleId} 模块...</Text>
+    </View>
+  );
+}
+
+const styles = StyleSheet.create({
+  container: {
+    flex: 1,
+    justifyContent: 'center',
+    alignItems: 'center',
+    backgroundColor: '#f5f5f5',
+  },
+  text: {
+    marginTop: 16,
+    fontSize: 16,
+    color: '#666',
+  },
+});
+