@bm-fe/react-native-multi-bundle 1.0.0-beta.12 → 1.0.0-beta.13

package/README.md

@@ -8,6 +8,7 @@ React Native 多 Bundle 系统 - 支持模块按需加载和独立更新
 - ✅ **模块依赖管理**：自动处理模块间的依赖关系
 - ✅ **模块状态管理**：完整的生命周期管理（idle/loading/loaded/failed）
 - ✅ **路由加载器**：`createModuleRouteLoader`，完美支持 React Navigation `getComponent` API
+- ✅ **错误处理与重试**：自动错误处理，支持重试机制和自定义错误组件
 - ✅ **预加载支持**：`preloadModule` 支持关键模块预加载
 - ✅ **开发环境 Mock**：开发环境无需 Native 模块即可运行
 - ✅ **TypeScript 支持**：完整的类型定义
@@ -79,6 +80,32 @@ export const createHomeScreen = createModuleRouteLoader('home', 'Home');
 <Stack.Screen name="Home" getComponent={createHomeScreen} />
 ```
 
+### 3. 自定义错误处理（可选）
+
+```typescript
+import { createModuleLoader, type ErrorFallbackProps } from '@bm-fe/react-native-multi-bundle';
+
+// 自定义错误组件
+function MyErrorFallback({ moduleId, error, onRetry }: ErrorFallbackProps) {
+  return (
+    <View>
+      <Text>模块 {moduleId} 加载失败</Text>
+      <Button title="重试" onPress={onRetry} />
+    </View>
+  );
+}
+
+// 使用自定义错误组件
+const createHomeScreen = createModuleLoader(
+  'home',
+  (exports) => exports.routes.Home,
+  {
+    ErrorFallback: MyErrorFallback,
+    onError: (error) => console.error('加载失败:', error),
+  }
+);
+```
+
 ## 完整集成指南
 
 详细的集成步骤请参考：[INTEGRATION.md](./INTEGRATION.md)

package/android/moduleloader/src/main/java/com/bitmart/exchange/module/loader/ModuleLoaderModule.kt

@@ -16,10 +16,8 @@ import kotlinx.coroutines.withContext
 import org.json.JSONObject
 import java.io.BufferedReader
 import java.io.File
-import java.io.FileOutputStream
 import java.io.FileReader
 import java.io.IOException
-import java.io.InputStream
 import java.io.InputStreamReader
 
 /**
@@ -27,10 +25,11 @@ import java.io.InputStreamReader
  *
  * 新架构下通过反射获取 ReactInstance，然后调用 loadJSBundle 方法
  * 注意：ReactInstance 是 internal 类，必须完全通过反射操作
- * 
- * Bundle 加载优先级：
- * 1. CodePush 目录（热更新后的 bundle）
- * 2. Assets（APK 内置的 bundle）
+ *
+ * Bundle 加载优先级（解决 CodePush 增量更新只包含变化 bundle 的问题）：
+ * 1. CodePush 当前 package hash 目录（最新热更新的 bundle）
+ * 2. CodePush 历史 package hash 目录（按时间从新到旧遍历）
+ * 3. Assets（APK 内置的 bundle，最终 fallback）
  */
 @ReactModule(name = ModuleLoaderModule.NAME)
 class ModuleLoaderModule(private val reactContext: ReactApplicationContext) : ReactContextBaseJavaModule(reactContext) {
@@ -38,7 +37,7 @@ class ModuleLoaderModule(private val reactContext: ReactApplicationContext) : Re
     companion object {
         const val NAME = "ModuleLoader"
         private const val TAG = "ModuleLoaderModule"
-        
+
         // CodePush 相关常量
         private const val CODE_PUSH_FOLDER_PREFIX = "CodePush"
         private const val STATUS_FILE = "codepush.json"
@@ -102,7 +101,7 @@ class ModuleLoaderModule(private val reactContext: ReactApplicationContext) : Re
 
         Log.d(TAG, "Using CatalystInstance (same JS Runtime guaranteed)")
         try {
-            // 1️⃣ 优先从 CodePush 目录加载
+            // 1️⃣ 优先从 CodePush 目录加载（当前包 → 历史包）
             val codePushBundlePath = getCodePushBundlePath(bundlePath)
             if (codePushBundlePath != null) {
                 Log.d(TAG, "Loading bundle from CodePush: $codePushBundlePath")
@@ -111,8 +110,8 @@ class ModuleLoaderModule(private val reactContext: ReactApplicationContext) : Re
                 promise.resolve(Arguments.createMap().apply { putBoolean("success", true) })
                 return true
             }
-            
-            // 2️⃣ 回退到 assets 加载
+
+            // 2️⃣ 回退到 assets 加载（APK 内置）
             val assetPath = "assets://$bundlePath"
             Log.d(TAG, "Loading bundle from assets: $assetPath")
             catalystInstance.loadScriptFromAssets(reactContext.assets, assetPath, false)
@@ -144,19 +143,19 @@ class ModuleLoaderModule(private val reactContext: ReactApplicationContext) : Re
         }
 
         Log.d(TAG, "Using ReactHostImpl (new architecture)")
-        
-        // 1️⃣ 优先从 CodePush 目录加载
+
+        // 1️⃣ 优先从 CodePush 目录加载（当前包 → 历史包）
         val codePushBundlePath = getCodePushBundlePath(bundlePath)
         val bundleLoader = if (codePushBundlePath != null) {
             Log.d(TAG, "Loading bundle from CodePush: $codePushBundlePath")
             JSBundleLoader.createFileLoader(codePushBundlePath)
         } else {
-            // 2️⃣ 回退到 assets 加载
+            // 2️⃣ 回退到 assets 加载（APK 内置）
             val assetUrl = "assets://$bundlePath"
             Log.d(TAG, "Loading bundle from assets: $assetUrl")
             JSBundleLoader.createAssetLoader(reactContext, assetUrl, false)
         }
-        
+
         loadBundleViaReflection(reactHost, bundleLoader, bundleId, promise)
         return true
     }
@@ -228,21 +227,21 @@ class ModuleLoaderModule(private val reactContext: ReactApplicationContext) : Re
         return try {
             val statusFilePath = "${getCodePushPath()}/$STATUS_FILE"
             val statusFile = File(statusFilePath)
-            
+
             if (!statusFile.exists()) {
                 Log.d(TAG, "CodePush status file not found: $statusFilePath")
                 return null
             }
-            
+
             val content = statusFile.readText()
             val json = JSONObject(content)
             val packageHash = json.optString(CURRENT_PACKAGE_KEY, null)
-            
+
             if (packageHash.isNullOrEmpty()) {
                 Log.d(TAG, "No current package hash in CodePush status")
                 return null
             }
-            
+
             Log.d(TAG, "Current CodePush package hash: $packageHash")
             packageHash
         } catch (e: Exception) {
@@ -261,70 +260,125 @@ class ModuleLoaderModule(private val reactContext: ReactApplicationContext) : Re
 
     /**
      * 从 CodePush 目录查找子 bundle 文件
-     * 
-     * 查找顺序：
-     * 1. <packageFolder>/modules/<bundleFileName>
-     * 2. <packageFolder>/<bundlePath>
-     * 3. <packageFolder>/<bundleFileName>
-     * 
+     *
+     * 查找优先级（解决增量更新只包含变化 bundle 的问题）：
+     * 1. 当前 package hash 目录
+     * 2. 按时间从新到旧遍历其他 package hash 目录
+     * 3. 如果都找不到，返回 null，由调用方从 assets:// 加载
+     *
+     * 每个目录内的查找顺序：
+     * 1. <folder>/modules/<bundleFileName>
+     * 2. <folder>/<bundlePath>
+     * 3. <folder>/<bundleFileName>
+     *
      * @param bundlePath 原始 bundle 路径，如 "modules/home.jsbundle"
-     * @return 完整的文件路径，如果不存在返回 null
+     * @return 完整的文件路径，如果不存在返回 null（调用方会从 assets:// 加载）
      */
     private fun getCodePushBundlePath(bundlePath: String): String? {
-        val packageHash = getCurrentPackageHash() ?: return null
-        val packageFolder = getPackageFolderPath(packageHash)
-        
-        // 检查包目录是否存在
-        val packageDir = File(packageFolder)
-        if (!packageDir.exists()) {
-            Log.d(TAG, "CodePush package folder not found: $packageFolder")
+        val codePushDir = File(getCodePushPath())
+
+        // CodePush 目录不存在，直接返回 null（调用方会从 assets:// 加载）
+        if (!codePushDir.exists()) {
+            Log.d(TAG, "CodePush directory not found, will load from assets")
             return null
         }
-        
-        // 提取文件名
+
         val bundleFileName = File(bundlePath).name
-        
-        // 查找路径列表
+        val currentPackageHash = getCurrentPackageHash()
+
+        // 1️⃣ 优先从当前 package hash 目录查找
+        if (currentPackageHash != null) {
+            val currentPackageFolder = getPackageFolderPath(currentPackageHash)
+            val foundPath = findBundleInFolder(currentPackageFolder, bundlePath, bundleFileName)
+            if (foundPath != null) {
+                Log.d(TAG, "Found bundle in current package: $foundPath")
+                return foundPath
+            }
+            Log.d(TAG, "Bundle not found in current package ($currentPackageHash), searching other packages...")
+        }
+
+        // 2️⃣ 按时间从新到旧遍历其他 package hash 目录
+        val otherPackageFolders = getPackageFoldersSortedByTime(codePushDir, currentPackageHash)
+        for (packageFolder in otherPackageFolders) {
+            val foundPath = findBundleInFolder(packageFolder.absolutePath, bundlePath, bundleFileName)
+            if (foundPath != null) {
+                Log.d(TAG, "Found bundle in previous package (${packageFolder.name}): $foundPath")
+                return foundPath
+            }
+        }
+
+        Log.d(TAG, "Bundle not found in CodePush directories, will load from assets: $bundlePath")
+        return null
+    }
+
+    /**
+     * 在指定文件夹中查找 bundle 文件
+     *
+     * 查找顺序：
+     * 1. <folder>/modules/<bundleFileName>
+     * 2. <folder>/<bundlePath>
+     * 3. <folder>/<bundleFileName>
+     */
+    private fun findBundleInFolder(folderPath: String, bundlePath: String, bundleFileName: String): String? {
+        val folder = File(folderPath)
+        if (!folder.exists() || !folder.isDirectory) {
+            return null
+        }
+
         val searchPaths = listOf(
-            // 1. <packageFolder>/modules/<bundleFileName>
-            "$packageFolder/modules/$bundleFileName",
-            // 2. <packageFolder>/<bundlePath> (完整相对路径)
-            "$packageFolder/$bundlePath",
-            // 3. <packageFolder>/<bundleFileName> (仅文件名)
-            "$packageFolder/$bundleFileName"
+            "$folderPath/modules/$bundleFileName",
+            "$folderPath/$bundlePath",
+            "$folderPath/$bundleFileName"
         )
-        
+
         for (path in searchPaths) {
             val file = File(path)
             if (file.exists() && file.isFile) {
-                Log.d(TAG, "Found bundle in CodePush: $path")
                 return path
             }
         }
-        
-        Log.d(TAG, "Bundle not found in CodePush package, searched: $searchPaths")
+
         return null
     }
 
+    /**
+     * 获取所有 package 目录，按修改时间从新到旧排序
+     * 排除当前 package、assets-base 和 codepush.json 等非 package 目录/文件
+     */
+    private fun getPackageFoldersSortedByTime(codePushDir: File, currentPackageHash: String?): List<File> {
+        val excludedNames = setOf(STATUS_FILE, "download", "unzipped")
+
+        return codePushDir.listFiles()
+            ?.filter { file ->
+                file.isDirectory &&
+                file.name != currentPackageHash &&
+                !excludedNames.contains(file.name)
+            }
+            ?.sortedByDescending { it.lastModified() }
+            ?: emptyList()
+    }
+
     // ==================== Bundle Manifest Support ====================
 
     /**
      * 获取当前 bundle manifest 文件路径
-     * 
+     *
      * 查找优先级：
      * 1. CodePush 当前包目录（热更新后的 manifest）
-     * 2. assets-base 目录（初始复制的 manifest）
+     * 2. 返回 null（调用方应使用 getCurrentBundleManifestContent 获取内容）
+     *
+     * 注意：如果需要从 assets 读取，请使用 getCurrentBundleManifestContent
      */
     @ReactMethod
     fun getCurrentBundleManifest(promise: Promise) {
         try {
-            // 1️⃣ 优先从 CodePush 当前包目录获取
+            // 优先从 CodePush 当前包目录获取
             val packageHash = getCurrentPackageHash()
             if (packageHash != null) {
                 val packageFolder = getPackageFolderPath(packageHash)
                 val codePushManifestPath = "$packageFolder/bundle-manifest.json"
                 val codePushManifestFile = File(codePushManifestPath)
-                
+
                 if (codePushManifestFile.exists()) {
                     Log.d(TAG, "Found manifest in CodePush package: $codePushManifestPath")
                     promise.resolve(codePushManifestPath)
@@ -332,22 +386,8 @@ class ModuleLoaderModule(private val reactContext: ReactApplicationContext) : Re
                 }
             }
 
-            // 2️⃣ 确保 assets-base 目录已初始化
-            ensureCodePushDirectoryInitialized()
-
-            // 从 assets-base 目录获取 manifest
-            val codePushDir = getCodePushPath()
-            val assetsBaseManifestPath = "$codePushDir/assets-base/bundle-manifest.json"
-            val assetsBaseManifestFile = File(assetsBaseManifestPath)
-
-            if (assetsBaseManifestFile.exists()) {
-                Log.d(TAG, "Found manifest in assets-base: $assetsBaseManifestPath")
-                promise.resolve(assetsBaseManifestPath)
-                return
-            }
-
-            // 如果都不存在，返回 null
-            Log.w(TAG, "Bundle manifest not found in any location")
+            // CodePush 中找不到，返回 null（调用方应使用 getCurrentBundleManifestContent）
+            Log.d(TAG, "Manifest not in CodePush, use getCurrentBundleManifestContent to read from assets")
             promise.resolve(null)
         } catch (e: Exception) {
             Log.e(TAG, "Failed to get current bundle manifest: ${e.message}")
@@ -357,10 +397,10 @@ class ModuleLoaderModule(private val reactContext: ReactApplicationContext) : Re
 
     /**
      * 获取当前 bundle manifest 文件内容
-     * 
+     *
      * 查找优先级：
      * 1. CodePush 当前包目录（热更新后的 manifest）
-     * 2. assets-base 目录（初始复制的 manifest）
+     * 2. APK 内置 assets（最终 fallback）
      */
     @ReactMethod
     fun getCurrentBundleManifestContent(promise: Promise) {
@@ -373,7 +413,7 @@ class ModuleLoaderModule(private val reactContext: ReactApplicationContext) : Re
                         val packageFolder = getPackageFolderPath(packageHash)
                         val codePushManifestPath = "$packageFolder/bundle-manifest.json"
                         val codePushManifestFile = File(codePushManifestPath)
-                        
+
                         if (codePushManifestFile.exists()) {
                             val content = readFileContent(codePushManifestFile)
                             if (content != null) {
@@ -382,25 +422,15 @@ class ModuleLoaderModule(private val reactContext: ReactApplicationContext) : Re
                             }
                         }
                     }
-                    
-                    // 2️⃣ 确保 assets-base 目录已初始化
-                    ensureCodePushDirectoryInitialized()
-
-                    // 从 assets-base 目录读取 manifest
-                    val codePushDir = getCodePushPath()
-                    val assetsBaseManifestPath = "$codePushDir/assets-base/bundle-manifest.json"
-                    val assetsBaseManifestFile = File(assetsBaseManifestPath)
-
-                    if (assetsBaseManifestFile.exists()) {
-                        val content = readFileContent(assetsBaseManifestFile)
-                        if (content != null) {
-                            Log.d(TAG, "✓ Read bundle manifest from assets-base directory")
-                            return@withContext content
-                        }
+
+                    // 2️⃣ 从 APK 内置 assets 读取
+                    val assetsContent = readAssetContent("bundle-manifest.json")
+                    if (assetsContent != null) {
+                        Log.d(TAG, "✓ Read bundle manifest from assets")
+                        return@withContext assetsContent
                     }
 
-                    // 如果都不存在，返回 null
-                    Log.w(TAG, "Bundle manifest content not found in any location")
+                    Log.w(TAG, "Bundle manifest not found in any location")
                     null
                 }
                 promise.resolve(manifestContent)
@@ -412,116 +442,25 @@ class ModuleLoaderModule(private val reactContext: ReactApplicationContext) : Re
     }
 
     /**
-     * 确保 CodePush 目录已从 assets 初始化
+     * 从 assets 读取文件内容
      */
-    private fun ensureCodePushDirectoryInitialized() {
-        try {
-            val codePushDir = "${reactContext.filesDir.absolutePath}/CodePush"
-            val assetsBaseDir = "$codePushDir/assets-base"
-
-            // 检查 assets-base 目录是否有 bundle-manifest.json 和 modules
-            val manifestFile = File("$assetsBaseDir/bundle-manifest.json")
-            val modulesDir = File("$assetsBaseDir/modules")
-
-            // 如果任一不存在，从 assets 复制
-            if (!manifestFile.exists() || !modulesDir.exists()) {
-                Log.d(TAG, "Initializing CodePush directory from assets...")
-                copyAssetsToCodePushDirectory(codePushDir)
-            }
-        } catch (e: Exception) {
-            Log.e(TAG, "Failed to initialize CodePush directory: ${e.message}")
-        }
-    }
-
-    /**
-     * 从 assets 复制 bundle-manifest.json 和 modules 目录到 CodePush 目录
-     */
-    private fun copyAssetsToCodePushDirectory(codePushDir: String) {
-        try {
-            // 创建 assets-base 目录
-            val defaultPackageDir = "$codePushDir/assets-base"
-            val defaultPackageDirFile = File(defaultPackageDir)
-            if (!defaultPackageDirFile.exists()) {
-                defaultPackageDirFile.mkdirs()
-            }
-
-            // 1. 复制 bundle-manifest.json
-            try {
-                val manifestAssetPath = "bundle-manifest.json"
-                val manifestInput = reactContext.assets.open(manifestAssetPath)
-                val manifestOutput = File("$defaultPackageDir/bundle-manifest.json")
-                copyInputStreamToFile(manifestInput, manifestOutput)
-                Log.d(TAG, "✓ Copied bundle-manifest.json to CodePush directory")
-            } catch (e: IOException) {
-                Log.w(TAG, "Warning: Could not copy bundle-manifest.json: ${e.message}")
-            }
-
-            // 2. 复制 modules 目录
-            try {
-                val modulesAssetPath = "modules"
-                val modulesOutputDir = File("$defaultPackageDir/modules")
-                if (!modulesOutputDir.exists()) {
-                    modulesOutputDir.mkdirs()
-                }
-
-                copyAssetFolder(modulesAssetPath, modulesOutputDir.absolutePath)
-                Log.d(TAG, "✓ Copied modules directory to CodePush directory")
-            } catch (e: IOException) {
-                Log.w(TAG, "Warning: Could not copy modules directory: ${e.message}")
-            }
-
-        } catch (e: Exception) {
-            Log.e(TAG, "Failed to copy assets to CodePush directory: ${e.message}")
-        }
-    }
-
-    /**
-     * 递归复制 asset 文件夹
-     */
-    @Throws(IOException::class)
-    private fun copyAssetFolder(assetPath: String, targetPath: String) {
-        val assets = reactContext.assets.list(assetPath)
-        if (assets.isNullOrEmpty()) {
-            // 这是一个文件，不是目录
-            val input = reactContext.assets.open(assetPath)
-            val output = File(targetPath)
-            copyInputStreamToFile(input, output)
-        } else {
-            // 这是一个目录
-            val dir = File(targetPath)
-            if (!dir.exists()) {
-                dir.mkdirs()
-            }
-
-            for (asset in assets) {
-                val subAssetPath = "$assetPath/$asset"
-                val subTargetPath = "$targetPath/$asset"
-                copyAssetFolder(subAssetPath, subTargetPath)
-            }
-        }
-    }
-
-    /**
-     * 将 InputStream 复制到文件
-     */
-    @Throws(IOException::class)
-    private fun copyInputStreamToFile(input: InputStream, output: File) {
-        var outputStream: FileOutputStream? = null
-        try {
-            outputStream = FileOutputStream(output)
-            val buffer = ByteArray(4096)
-            var bytesRead: Int
-            while (input.read(buffer).also { bytesRead = it } != -1) {
-                outputStream.write(buffer, 0, bytesRead)
+    private fun readAssetContent(assetPath: String): String? {
+        var reader: BufferedReader? = null
+        return try {
+            val inputStream = reactContext.assets.open(assetPath)
+            reader = BufferedReader(InputStreamReader(inputStream))
+            val content = StringBuilder()
+            var line: String?
+            while (reader.readLine().also { line = it } != null) {
+                content.append(line).append("\n")
             }
+            content.toString()
+        } catch (e: IOException) {
+            Log.e(TAG, "Failed to read asset: $assetPath - ${e.message}")
+            null
         } finally {
             try {
-                input.close()
-            } catch (e: IOException) {
-                // Ignore
-            }
-            try {
-                outputStream?.close()
+                reader?.close()
             } catch (e: IOException) {
                 // Ignore
             }

package/ios/ModuleLoader/ModuleLoaderModule.mm

@@ -18,6 +18,11 @@ RCT_EXPORT_MODULE(ModuleLoader);
 // Bundle manifest file name
 static NSString *const BundleManifestFileName = @"bundle-manifest.json";
 
+// CodePush 相关常量
+static NSString *const CodePushFolderPrefix = @"CodePush";
+static NSString *const StatusFileName = @"codepush.json";
+static NSString *const CurrentPackageKey = @"currentPackage";
+
 #pragma mark - Bundle Path Resolution
 
 /**
@@ -84,7 +89,212 @@ static NSString *const BundleManifestFileName = @"bundle-manifest.json";
     return nil;
 }
 
+#pragma mark - CodePush Bundle Path Resolution
+
+/**
+ * 获取 CodePush 基础目录
+ * 路径: <ApplicationSupport>/CodePush/ 或 <Documents>/CodePush/
+ */
+- (NSString *)getCodePushPath {
+    // 优先使用 Application Support 目录
+    NSString *appSupportPath = [NSSearchPathForDirectoriesInDomains(NSApplicationSupportDirectory, NSUserDomainMask, YES) firstObject];
+    NSString *codePushPath = [appSupportPath stringByAppendingPathComponent:CodePushFolderPrefix];
+
+    if ([[NSFileManager defaultManager] fileExistsAtPath:codePushPath]) {
+        return codePushPath;
+    }
+
+    // 回退到 Documents 目录
+    NSString *documentsPath = [NSSearchPathForDirectoriesInDomains(NSDocumentDirectory, NSUserDomainMask, YES) firstObject];
+    codePushPath = [documentsPath stringByAppendingPathComponent:CodePushFolderPrefix];
+
+    if ([[NSFileManager defaultManager] fileExistsAtPath:codePushPath]) {
+        return codePushPath;
+    }
+
+    return nil;
+}
+
+/**
+ * 获取当前 CodePush 包的 hash
+ * 从 <CodePushPath>/codepush.json 读取 currentPackage 字段
+ */
+- (NSString *)getCurrentPackageHash {
+    NSString *codePushPath = [self getCodePushPath];
+    if (!codePushPath) {
+        return nil;
+    }
+
+    NSString *statusFilePath = [codePushPath stringByAppendingPathComponent:StatusFileName];
+
+    if (![[NSFileManager defaultManager] fileExistsAtPath:statusFilePath]) {
+        RCTLogInfo(@"[ModuleLoader] CodePush status file not found: %@", statusFilePath);
+        return nil;
+    }
+
+    @try {
+        NSData *data = [NSData dataWithContentsOfFile:statusFilePath];
+        if (!data) {
+            return nil;
+        }
+
+        NSDictionary *json = [NSJSONSerialization JSONObjectWithData:data options:0 error:nil];
+        NSString *packageHash = json[CurrentPackageKey];
+
+        if (packageHash && packageHash.length > 0) {
+            RCTLogInfo(@"[ModuleLoader] Current CodePush package hash: %@", packageHash);
+            return packageHash;
+        }
+    } @catch (NSException *exception) {
+        RCTLogWarn(@"[ModuleLoader] Error reading CodePush status: %@", exception.reason);
+    }
+
+    return nil;
+}
+
+/**
+ * 获取 CodePush 包目录路径
+ * 路径: <CodePushPath>/<packageHash>/
+ */
+- (NSString *)getPackageFolderPath:(NSString *)packageHash {
+    NSString *codePushPath = [self getCodePushPath];
+    if (!codePushPath) {
+        return nil;
+    }
+    return [codePushPath stringByAppendingPathComponent:packageHash];
+}
+
+/**
+ * 在指定文件夹中查找 bundle 文件
+ *
+ * 查找顺序：
+ * 1. <folder>/modules/<bundleFileName>
+ * 2. <folder>/<bundlePath>
+ * 3. <folder>/<bundleFileName>
+ */
+- (NSString *)findBundleInFolder:(NSString *)folderPath
+                      bundlePath:(NSString *)bundlePath
+                  bundleFileName:(NSString *)bundleFileName {
+    NSFileManager *fileManager = [NSFileManager defaultManager];
+
+    BOOL isDirectory;
+    if (![fileManager fileExistsAtPath:folderPath isDirectory:&isDirectory] || !isDirectory) {
+        return nil;
+    }
+
+    NSArray<NSString *> *searchPaths = @[
+        [folderPath stringByAppendingPathComponent:[@"modules/" stringByAppendingString:bundleFileName]],
+        [folderPath stringByAppendingPathComponent:bundlePath],
+        [folderPath stringByAppendingPathComponent:bundleFileName]
+    ];
+
+    for (NSString *path in searchPaths) {
+        if ([fileManager fileExistsAtPath:path]) {
+            return path;
+        }
+    }
+
+    return nil;
+}
+
+/**
+ * 获取所有 package 目录，按修改时间从新到旧排序
+ * 排除当前 package 和非 package 目录/文件
+ */
+- (NSArray<NSString *> *)getPackageFoldersSortedByTime:(NSString *)codePushDir
+                                    currentPackageHash:(NSString *)currentPackageHash {
+    NSFileManager *fileManager = [NSFileManager defaultManager];
+    NSSet *excludedNames = [NSSet setWithArray:@[StatusFileName, @"download", @"unzipped"]];
+
+    NSError *error;
+    NSArray<NSString *> *contents = [fileManager contentsOfDirectoryAtPath:codePushDir error:&error];
+    if (error || !contents) {
+        return @[];
+    }
+
+    NSMutableArray<NSDictionary *> *packageFolders = [NSMutableArray array];
+
+    for (NSString *name in contents) {
+        // 排除非 package 目录
+        if ([excludedNames containsObject:name]) {
+            continue;
+        }
+        if (currentPackageHash && [name isEqualToString:currentPackageHash]) {
+            continue;
+        }
+
+        NSString *fullPath = [codePushDir stringByAppendingPathComponent:name];
+        BOOL isDirectory;
+        if ([fileManager fileExistsAtPath:fullPath isDirectory:&isDirectory] && isDirectory) {
+            NSDictionary *attrs = [fileManager attributesOfItemAtPath:fullPath error:nil];
+            NSDate *modDate = attrs[NSFileModificationDate] ?: [NSDate distantPast];
+            [packageFolders addObject:@{@"path": fullPath, @"date": modDate}];
+        }
+    }
+
+    // 按修改时间从新到旧排序
+    [packageFolders sortUsingComparator:^NSComparisonResult(NSDictionary *a, NSDictionary *b) {
+        return [b[@"date"] compare:a[@"date"]];
+    }];
+
+    NSMutableArray<NSString *> *sortedPaths = [NSMutableArray array];
+    for (NSDictionary *folder in packageFolders) {
+        [sortedPaths addObject:folder[@"path"]];
+    }
+
+    return sortedPaths;
+}
+
+/**
+ * 从 CodePush 目录查找子 bundle 文件
+ *
+ * 查找优先级（解决增量更新只包含变化 bundle 的问题）：
+ * 1. 当前 package hash 目录
+ * 2. 按时间从新到旧遍历其他 package hash 目录
+ * 3. 如果都找不到，返回 nil，由调用方从内置目录加载
+ *
+ * @param bundlePath 原始 bundle 路径，如 "modules/home.jsbundle"
+ * @return 完整的文件路径，如果不存在返回 nil
+ */
 - (NSString *)getCodePushBundlePath:(NSString *)bundlePath {
+    NSString *codePushDir = [self getCodePushPath];
+
+    // CodePush 目录不存在，直接返回 nil
+    if (!codePushDir) {
+        RCTLogInfo(@"[ModuleLoader] CodePush directory not found, will load from MainBundle");
+        return nil;
+    }
+
+    NSString *bundleFileName = [bundlePath lastPathComponent];
+    NSString *currentPackageHash = [self getCurrentPackageHash];
+
+    // 1️⃣ 优先从当前 package hash 目录查找
+    if (currentPackageHash) {
+        NSString *currentPackageFolder = [self getPackageFolderPath:currentPackageHash];
+        NSString *foundPath = [self findBundleInFolder:currentPackageFolder
+                                            bundlePath:bundlePath
+                                        bundleFileName:bundleFileName];
+        if (foundPath) {
+            RCTLogInfo(@"[ModuleLoader] Found bundle in current package: %@", foundPath);
+            return foundPath;
+        }
+        RCTLogInfo(@"[ModuleLoader] Bundle not found in current package (%@), searching other packages...", currentPackageHash);
+    }
+
+    // 2️⃣ 按时间从新到旧遍历其他 package hash 目录
+    NSArray<NSString *> *otherPackageFolders = [self getPackageFoldersSortedByTime:codePushDir
+                                                                currentPackageHash:currentPackageHash];
+    for (NSString *packageFolder in otherPackageFolders) {
+        NSString *foundPath = [self findBundleInFolder:packageFolder
+                                            bundlePath:bundlePath
+                                        bundleFileName:bundleFileName];
+        if (foundPath) {
+            RCTLogInfo(@"[ModuleLoader] Found bundle in previous package (%@): %@", [packageFolder lastPathComponent], foundPath);
+            return foundPath;
+        }
+    }
+
+    RCTLogInfo(@"[ModuleLoader] Bundle not found in CodePush directories, will load from MainBundle: %@", bundlePath);
     return nil;
 }
 
@@ -330,14 +540,6 @@ RCT_EXPORT_METHOD(loadBusinessBundle:(NSString *)bundleId
 
 #pragma mark - Bundle Manifest Methods
 
-+ (NSString *)getApplicationSupportDirectory {
-    return [NSSearchPathForDirectoriesInDomains(NSApplicationSupportDirectory, NSUserDomainMask, YES) objectAtIndex:0];
-}
-
-+ (NSString *)bundleAssetsPath {
-    return [[[NSBundle mainBundle] resourcePath] stringByAppendingPathComponent:@"assets"];
-}
-
 - (NSString *)readFileContent:(NSString *)filePath {
     @try {
         NSError *error;
@@ -359,7 +561,19 @@ RCT_EXPORT_METHOD(getCurrentBundleManifest:(RCTPromiseResolveBlock)resolve
     @try {
         NSFileManager *fileManager = [NSFileManager defaultManager];
 
-        // 1. MainBundle/Bundles 目录
+        // 1️⃣ 优先从 CodePush 当前包目录获取
+        NSString *packageHash = [self getCurrentPackageHash];
+        if (packageHash) {
+            NSString *packageFolder = [self getPackageFolderPath:packageHash];
+            NSString *codePushManifestPath = [packageFolder stringByAppendingPathComponent:BundleManifestFileName];
+            if ([fileManager fileExistsAtPath:codePushManifestPath]) {
+                RCTLogInfo(@"[ModuleLoader] Found manifest in CodePush package: %@", codePushManifestPath);
+                resolve(codePushManifestPath);
+                return;
+            }
+        }
+
+        // 2️⃣ MainBundle/Bundles 目录（内置）
         NSString *bundlesPath = [[[NSBundle mainBundle] bundlePath] stringByAppendingPathComponent:@"Bundles"];
         NSString *bundlesManifestPath = [bundlesPath stringByAppendingPathComponent:BundleManifestFileName];
         if ([fileManager fileExistsAtPath:bundlesManifestPath]) {
@@ -368,33 +582,7 @@ RCT_EXPORT_METHOD(getCurrentBundleManifest:(RCTPromiseResolveBlock)resolve
             return;
         }
 
-        // 2. Documents 目录
-        NSString *documentsPath = [NSSearchPathForDirectoriesInDomains(NSDocumentDirectory, NSUserDomainMask, YES) firstObject];
-        if (documentsPath) {
-            NSString *documentsManifestPath = [documentsPath stringByAppendingPathComponent:BundleManifestFileName];
-            if ([fileManager fileExistsAtPath:documentsManifestPath]) {
-                resolve(documentsManifestPath);
-                return;
-            }
-        }
-
-        // 3. Application Support 目录
-        NSString *appSupportPath = [[self class] getApplicationSupportDirectory];
-        NSString *appSupportManifestPath = [appSupportPath stringByAppendingPathComponent:BundleManifestFileName];
-        if ([fileManager fileExistsAtPath:appSupportManifestPath]) {
-            resolve(appSupportManifestPath);
-            return;
-        }
-
-        // 4. MainBundle assets 目录
-        NSString *assetsPath = [[self class] bundleAssetsPath];
-        NSString *assetsManifestPath = [assetsPath stringByAppendingPathComponent:BundleManifestFileName];
-        if ([fileManager fileExistsAtPath:assetsManifestPath]) {
-            resolve(assetsManifestPath);
-            return;
-        }
-
-        // 5. MainBundle 根目录
+        // 3️⃣ MainBundle 根目录
         NSString *mainBundleManifestPath = [[[NSBundle mainBundle] bundlePath] stringByAppendingPathComponent:BundleManifestFileName];
         if ([fileManager fileExistsAtPath:mainBundleManifestPath]) {
             resolve(mainBundleManifestPath);
@@ -417,58 +605,39 @@ RCT_EXPORT_METHOD(getCurrentBundleManifestContent:(RCTPromiseResolveBlock)resolv
             NSFileManager *fileManager = [NSFileManager defaultManager];
             NSString *manifestContent = nil;
 
-            // 1. MainBundle/Bundles 目录
-            NSString *bundlesPath = [[[NSBundle mainBundle] bundlePath] stringByAppendingPathComponent:@"Bundles"];
-            NSString *bundlesManifestPath = [bundlesPath stringByAppendingPathComponent:BundleManifestFileName];
-            if ([fileManager fileExistsAtPath:bundlesManifestPath]) {
-                manifestContent = [self readFileContent:bundlesManifestPath];
-                if (manifestContent) {
-                    RCTLogInfo(@"[ModuleLoader] Read manifest from Bundles");
-                    dispatch_async(dispatch_get_main_queue(), ^{ resolve(manifestContent); });
-                    return;
-                }
-            }
-
-            // 2. Documents 目录
-            NSString *documentsPath = [NSSearchPathForDirectoriesInDomains(NSDocumentDirectory, NSUserDomainMask, YES) firstObject];
-            if (documentsPath) {
-                NSString *documentsManifestPath = [documentsPath stringByAppendingPathComponent:BundleManifestFileName];
-                if ([fileManager fileExistsAtPath:documentsManifestPath]) {
-                    manifestContent = [self readFileContent:documentsManifestPath];
+            // 1️⃣ 优先从 CodePush 当前包目录读取
+            NSString *packageHash = [self getCurrentPackageHash];
+            if (packageHash) {
+                NSString *packageFolder = [self getPackageFolderPath:packageHash];
+                NSString *codePushManifestPath = [packageFolder stringByAppendingPathComponent:BundleManifestFileName];
+                if ([fileManager fileExistsAtPath:codePushManifestPath]) {
+                    manifestContent = [self readFileContent:codePushManifestPath];
                     if (manifestContent) {
+                        RCTLogInfo(@"[ModuleLoader] ✓ Read manifest from CodePush package");
                         dispatch_async(dispatch_get_main_queue(), ^{ resolve(manifestContent); });
                         return;
                     }
                 }
             }
 
-            // 3. Application Support 目录
-            NSString *appSupportPath = [[self class] getApplicationSupportDirectory];
-            NSString *appSupportManifestPath = [appSupportPath stringByAppendingPathComponent:BundleManifestFileName];
-            if ([fileManager fileExistsAtPath:appSupportManifestPath]) {
-                manifestContent = [self readFileContent:appSupportManifestPath];
-                if (manifestContent) {
-                    dispatch_async(dispatch_get_main_queue(), ^{ resolve(manifestContent); });
-                    return;
-                }
-            }
-
-            // 4. MainBundle assets 目录
-            NSString *assetsPath = [[self class] bundleAssetsPath];
-            NSString *assetsManifestPath = [assetsPath stringByAppendingPathComponent:BundleManifestFileName];
-            if ([fileManager fileExistsAtPath:assetsManifestPath]) {
-                manifestContent = [self readFileContent:assetsManifestPath];
+            // 2️⃣ MainBundle/Bundles 目录（内置）
+            NSString *bundlesPath = [[[NSBundle mainBundle] bundlePath] stringByAppendingPathComponent:@"Bundles"];
+            NSString *bundlesManifestPath = [bundlesPath stringByAppendingPathComponent:BundleManifestFileName];
+            if ([fileManager fileExistsAtPath:bundlesManifestPath]) {
+                manifestContent = [self readFileContent:bundlesManifestPath];
                 if (manifestContent) {
+                    RCTLogInfo(@"[ModuleLoader] ✓ Read manifest from Bundles");
                     dispatch_async(dispatch_get_main_queue(), ^{ resolve(manifestContent); });
                     return;
                 }
             }
 
-            // 5. MainBundle 根目录
+            // 3️⃣ MainBundle 根目录
             NSString *mainBundleManifestPath = [[[NSBundle mainBundle] bundlePath] stringByAppendingPathComponent:BundleManifestFileName];
             if ([fileManager fileExistsAtPath:mainBundleManifestPath]) {
                 manifestContent = [self readFileContent:mainBundleManifestPath];
                 if (manifestContent) {
+                    RCTLogInfo(@"[ModuleLoader] ✓ Read manifest from MainBundle");
                     dispatch_async(dispatch_get_main_queue(), ^{ resolve(manifestContent); });
                     return;
                 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bm-fe/react-native-multi-bundle",
-  "version": "1.0.0-beta.12",
+  "version": "1.0.0-beta.13",
   "description": "React Native 多 Bundle 系统 - 支持模块按需加载和独立更新",
   "main": "src/index.ts",
   "types": "src/index.ts",

package/src/index.ts

@@ -18,7 +18,7 @@ export {
 } from './multi-bundle/config';
 
 // 模块加载器
-export { createModuleLoader, type CreateModuleLoaderOptions } from './multi-bundle/createModuleLoader';
+export { createModuleLoader, type CreateModuleLoaderOptions, type ErrorFallbackProps } from './multi-bundle/createModuleLoader';
 export { createModuleRouteLoader } from './multi-bundle/createModuleRouteLoader';
 
 // 模块预加载

package/src/multi-bundle/README.md

@@ -251,6 +251,8 @@ const createHomeScreen = createModuleRouteLoader('home', 'Home');
 <Stack.Screen name="Home" getComponent={createHomeScreen} />
 ```
 
+**注意**：`createModuleRouteLoader` 内部使用 `createModuleLoader`，因此也支持错误重试功能。如果模块加载失败，用户可以通过错误页面上的重试按钮重新加载模块。
+
 ### createModuleLoader
 
 创建通用的模块加载器函数（用于自定义组件提取逻辑）。
@@ -263,14 +265,60 @@ function createModuleLoader(
 ): () => React.ComponentType<any>
 ```
 
+**CreateModuleLoaderOptions**：
+```typescript
+interface CreateModuleLoaderOptions {
+  onError?: (error: Error) => void;  // 错误处理回调
+  ErrorFallback?: React.ComponentType<ErrorFallbackProps>;  // 自定义错误组件
+}
+```
+
+**ErrorFallbackProps**：
+```typescript
+interface ErrorFallbackProps {
+  moduleId: string;      // 模块 ID
+  error: Error | null;   // 错误对象
+  onRetry: () => void;   // 重试回调（点击重试按钮会触发重新加载）
+}
+```
+
 **使用示例**：
 ```typescript
+// 基础用法
 const createCustomScreen = createModuleLoader(
   'my-module',
   (exports) => exports.components.MyComponent
 );
+
+// 使用自定义错误组件
+import { ErrorFallbackProps } from '@bm-fe/react-native-multi-bundle';
+
+function MyCustomErrorFallback({ moduleId, error, onRetry }: ErrorFallbackProps) {
+  return (
+    <View>
+      <Text>模块 {moduleId} 加载失败</Text>
+      <Button title="重试" onPress={onRetry} />
+    </View>
+  );
+}
+
+const createCustomScreen = createModuleLoader(
+  'my-module',
+  (exports) => exports.components.MyComponent,
+  {
+    ErrorFallback: MyCustomErrorFallback,
+    onError: (error) => {
+      console.error('模块加载失败:', error);
+    },
+  }
+);
 ```
 
+**特性**：
+- ✅ 自动重试：点击重试按钮会触发模块重新加载
+- ✅ 自定义错误 UI：支持传入自定义错误组件
+- ✅ 错误回调：可通过 `onError` 监听加载失败事件
+
 
 ### registerModuleRoute
 

package/src/multi-bundle/createModuleLoader.tsx

@@ -11,8 +11,15 @@ import { ModuleErrorFallback } from './ModuleErrorFallback';
 
 type ModuleState = 'idle' | 'loading' | 'success' | 'error';
 
-interface CreateModuleLoaderOptions {
+export interface ErrorFallbackProps {
+  moduleId: string;
+  error: Error | null;
+  onRetry: () => void;
+}
+
+export interface CreateModuleLoaderOptions {
   onError?: (error: Error) => void;
+  ErrorFallback?: React.ComponentType<ErrorFallbackProps>;
 }
 
 /**
@@ -33,6 +40,7 @@ export function createModuleLoader(
       const [InnerComponent, setInnerComponent] =
         useState<React.ComponentType<any> | null>(null);
       const [error, setError] = useState<Error | null>(null);
+      const [retryCount, setRetryCount] = useState(0);
 
       useEffect(() => {
         let isMounted = true;
@@ -63,16 +71,18 @@ export function createModuleLoader(
         return () => {
           isMounted = false;
         };
-      }, [moduleId]);
+      }, [moduleId, retryCount]);
 
       if (state === 'error') {
+        const FallbackComponent = options.ErrorFallback || ModuleErrorFallback;
         return (
-          <ModuleErrorFallback
+          <FallbackComponent
             moduleId={moduleId}
             error={error}
             onRetry={() => {
               setState('idle');
               setError(null);
+              setRetryCount((c) => c + 1);
             }}
           />
         );