remote-reload-utils 0.0.14 → 0.0.17

package/dist/main.js

@@ -1,19 +1,4 @@
 import { createInstance } from "@module-federation/enhanced/runtime";
-import react, { Suspense, lazy, useCallback, useEffect, useState } from "react";
-var __webpack_modules__ = {
-    "./src/styles/index.css": function() {}
-};
-var __webpack_module_cache__ = {};
-function __webpack_require__(moduleId) {
-    var cachedModule = __webpack_module_cache__[moduleId];
-    if (void 0 !== cachedModule) return cachedModule.exports;
-    var module = __webpack_module_cache__[moduleId] = {
-        exports: {}
-    };
-    __webpack_modules__[moduleId](module, module.exports, __webpack_require__);
-    return module.exports;
-}
-__webpack_require__("./src/styles/index.css");
 async function loadReactVersion(version) {
     const runtime = await createInstance({
         name: `react_${version}_runtime`,
@@ -195,15 +180,46 @@ const DEFAULT_SHARED_CONFIG = {
         shareConfig: {
             singleton: true,
             eager: true,
-            requiredVersion: false
-        }
+            requiredVersion: false,
+            strictVersion: false
+        },
+        strategy: 'loaded-first'
     },
     'react-dom': {
         shareConfig: {
             singleton: true,
             eager: true,
-            requiredVersion: false
-        }
+            requiredVersion: false,
+            strictVersion: false
+        },
+        strategy: 'loaded-first'
+    },
+    'react-dom/client': {
+        shareConfig: {
+            singleton: true,
+            eager: true,
+            requiredVersion: false,
+            strictVersion: false
+        },
+        strategy: 'loaded-first'
+    },
+    'react/jsx-runtime': {
+        shareConfig: {
+            singleton: true,
+            eager: true,
+            requiredVersion: false,
+            strictVersion: false
+        },
+        strategy: 'loaded-first'
+    },
+    'react/jsx-dev-runtime': {
+        shareConfig: {
+            singleton: true,
+            eager: true,
+            requiredVersion: false,
+            strictVersion: false
+        },
+        strategy: 'loaded-first'
     }
 };
 async function fetchLatestVersion(pkg) {
@@ -238,9 +254,30 @@ function setVersionCache(pkg, version) {
 function buildCdnUrls(pkg, version) {
     return DEFAULT_CDN_TEMPLATES.map((template)=>template.replace('{pkg}', pkg).replace('{version}', version));
 }
-async function tryLoadRemote(scopeName, url, retries, delay, sharedConfig, plugins) {
-    let lastError;
-    for(let i = 0; i < retries; i++)try {
+const mfInstanceCache = new Map();
+const mfInstanceLoadingCache = new Map();
+function buildRemotesIdentity(remotes) {
+    if (0 === remotes.length) return '';
+    return remotes.map((remote)=>JSON.stringify({
+            name: remote.name,
+            entry: 'entry' in remote ? remote.entry : '',
+            version: 'version' in remote ? remote.version : '',
+            alias: remote.alias || '',
+            type: remote.type || '',
+            entryGlobalName: remote.entryGlobalName || ''
+        })).sort().join('|');
+}
+async function tryLoadRemote(scopeName, url, _retries, _delay, sharedConfig, plugins, extraRemotes = [], registerOptions = {}) {
+    const remotesIdentity = buildRemotesIdentity(extraRemotes);
+    const cacheKey = `${scopeName}::${url}::${remotesIdentity}::${registerOptions.force ? 'force' : 'normal'}`;
+    const cachedMfs = mfInstanceCache.get(cacheKey);
+    if (cachedMfs) return {
+        scopeName,
+        mf: cachedMfs
+    };
+    const loadingMfs = mfInstanceLoadingCache.get(cacheKey);
+    if (loadingMfs) return loadingMfs;
+    const loadPromise = Promise.resolve().then(()=>{
         const mf = createInstance({
             name: 'host',
             remotes: [
@@ -255,24 +292,111 @@ async function tryLoadRemote(scopeName, url, retries, delay, sharedConfig, plugi
                 fallbackPlugin()
             ]
         });
-        return {
+        if (extraRemotes.length > 0) mf.registerRemotes(extraRemotes, registerOptions);
+        const result = {
             scopeName,
             mf
         };
-    } catch (e) {
-        lastError = e;
-        console.warn(`[MF] URL ${url} 加载失败，第 ${i + 1} 次重试...`);
-        if (i < retries - 1) await new Promise((res)=>setTimeout(res, delay));
-    }
-    throw new Error(`[MF] URL ${url} 经过 ${retries} 次重试仍加载失败。`, {
-        cause: lastError
+        mfInstanceCache.set(cacheKey, mf);
+        return result;
     });
+    mfInstanceLoadingCache.set(cacheKey, loadPromise);
+    try {
+        return await loadPromise;
+    } finally{
+        mfInstanceLoadingCache.delete(cacheKey);
+    }
 }
 function getFinalSharedConfig(customShared) {
-    return {
+    const globalReact = window.React;
+    const globalReactDOM = window.ReactDOM;
+    const globalShared = {};
+    if (globalReact && globalReactDOM) {
+        const isValidReact = 'object' == typeof globalReact && 'function' == typeof globalReact.useCallback;
+        if (isValidReact) {
+            globalShared.react = {
+                version: globalReact.version || '18.0.0',
+                lib: ()=>globalReact,
+                shareConfig: {
+                    singleton: true,
+                    eager: true,
+                    requiredVersion: false,
+                    strictVersion: false
+                },
+                strategy: 'loaded-first'
+            };
+            globalShared['react-dom'] = {
+                version: globalReactDOM.version || '18.0.0',
+                lib: ()=>globalReactDOM,
+                shareConfig: {
+                    singleton: true,
+                    eager: true,
+                    requiredVersion: false,
+                    strictVersion: false
+                },
+                strategy: 'loaded-first'
+            };
+            globalShared['react-dom/client'] = {
+                version: globalReactDOM.version || '18.0.0',
+                lib: ()=>globalReactDOM,
+                shareConfig: {
+                    singleton: true,
+                    eager: true,
+                    requiredVersion: false,
+                    strictVersion: false
+                },
+                strategy: 'loaded-first'
+            };
+            console.log('[getFinalSharedConfig] Using global React instance', {
+                version: globalReact.version
+            });
+        } else console.warn('[getFinalSharedConfig] Global React found but is invalid', {
+            type: typeof globalReact,
+            useCallback: typeof globalReact?.useCallback
+        });
+    } else console.log('[getFinalSharedConfig] No global React found, using default shared config');
+    const mergedShared = {
         ...DEFAULT_SHARED_CONFIG,
+        ...globalShared,
         ...customShared || {}
     };
+    const keepSingletonPackages = [
+        'react',
+        'react-dom',
+        'react-dom/client',
+        'react/jsx-runtime',
+        'react/jsx-dev-runtime'
+    ];
+    for (const pkgName of keepSingletonPackages){
+        const base = mergedShared[pkgName] || {};
+        mergedShared[pkgName] = {
+            ...base,
+            strategy: 'loaded-first',
+            shareConfig: {
+                singleton: true,
+                eager: true,
+                requiredVersion: false,
+                strictVersion: false,
+                ...base.shareConfig || {}
+            }
+        };
+    }
+    if ('function' == typeof globalShared.react?.lib) mergedShared.react = {
+        ...mergedShared.react || {},
+        lib: globalShared.react.lib,
+        version: globalShared.react.version
+    };
+    if ('function' == typeof globalShared['react-dom']?.lib) mergedShared['react-dom'] = {
+        ...mergedShared['react-dom'] || {},
+        lib: globalShared['react-dom'].lib,
+        version: globalShared['react-dom'].version
+    };
+    if ('function' == typeof globalShared['react-dom/client']?.lib) mergedShared['react-dom/client'] = {
+        ...mergedShared['react-dom/client'] || {},
+        lib: globalShared['react-dom/client'].lib,
+        version: globalShared['react-dom/client'].version
+    };
+    return mergedShared;
 }
 async function resolveFinalVersion(pkg, version, cacheTTL, revalidate) {
     let finalVersion = version;
@@ -300,14 +424,55 @@ function buildFinalUrls(pkg, version, localFallback) {
     if (localFallback) urls.push(localFallback);
     return urls;
 }
-async function loadRemoteMultiVersion(options, plugins) {
+function dedupeRemotes(remotes) {
+    const map = new Map();
+    for (const remote of remotes){
+        if (!remote?.name) continue;
+        const key = [
+            remote.name,
+            'entry' in remote ? remote.entry || '' : '',
+            'version' in remote ? remote.version || '' : '',
+            remote.alias || ''
+        ].join('::');
+        if (!map.has(key)) map.set(key, remote);
+    }
+    return Array.from(map.values());
+}
+async function resolveRegisteredRemotes(context, baseRemotes, remoteSourcePlugins) {
+    const remoteList = [
+        ...baseRemotes
+    ];
+    for (const plugin of remoteSourcePlugins)if (plugin.registerRemotes) try {
+        const pluginRemotes = await plugin.registerRemotes(context);
+        if (pluginRemotes?.length) remoteList.push(...pluginRemotes);
+    } catch (error) {
+        throw new Error(`[MF] remote 来源插件 ${plugin.name} 执行失败: ${error.message}`);
+    }
+    return dedupeRemotes(remoteList).filter((remote)=>!(remote.name === context.scopeName && 'entry' in remote && remote.entry === context.currentEntry));
+}
+function createRemoteSourcePlugin(name, remotes) {
+    return {
+        name,
+        registerRemotes: ()=>remotes
+    };
+}
+async function loadRemoteMultiVersion(options, plugins = [], extraOptions = {}) {
     const { name, pkg, version = 'latest', retries = 3, delay = 1000, localFallback, cacheTTL = 86400000, revalidate = true, shared: customShared } = options;
+    const { remoteSourcePlugins = [], baseRemotes = [], registerOptions = {} } = extraOptions;
     const finalVersion = await resolveFinalVersion(pkg, version, cacheTTL, revalidate);
     const scopeName = `${name}`;
     const urls = buildFinalUrls(pkg, finalVersion, localFallback);
     const finalSharedConfig = getFinalSharedConfig(customShared);
     for (const url of urls)try {
-        return await tryLoadRemote(scopeName, url, retries, delay, finalSharedConfig, plugins);
+        const registeredRemotes = await resolveRegisteredRemotes({
+            options,
+            scopeName,
+            pkg,
+            finalVersion,
+            currentEntry: url,
+            allEntries: urls
+        }, baseRemotes, remoteSourcePlugins);
+        return await tryLoadRemote(scopeName, url, retries, delay, finalSharedConfig, plugins, registeredRemotes, registerOptions);
     } catch (e) {
         console.warn(`[MF] 切换 CDN 路径：${url} 失败，尝试下一个...`, e);
     }
@@ -699,291 +864,4 @@ const eventBus = EventBusClass.create();
 function createEventBus() {
     return EventBusClass.create();
 }
-class ErrorBoundary extends react.Component {
-    constructor(props){
-        super(props);
-        this.state = {
-            hasError: false,
-            error: null,
-            errorInfo: null
-        };
-    }
-    static getDerivedStateFromError(error) {
-        return {
-            hasError: true,
-            error,
-            errorInfo: null
-        };
-    }
-    componentDidCatch(error, errorInfo) {
-        this.setState({
-            errorInfo
-        });
-        this.props.onError?.(error, errorInfo);
-        console.error('[RemoteReloadUtils] ErrorBoundary caught error:', error, errorInfo);
-    }
-    handleReset = ()=>{
-        this.setState({
-            hasError: false,
-            error: null,
-            errorInfo: null
-        });
-        this.props.onReset?.();
-    };
-    render() {
-        if (this.state.hasError && this.state.error) {
-            if ('function' == typeof this.props.fallback) return this.props.fallback(this.state.error, this.handleReset);
-            if (void 0 !== this.props.fallback) return this.props.fallback;
-            return /*#__PURE__*/ react.createElement("div", {
-                role: "alert",
-                className: "p-4 border border-red-200 bg-red-50 rounded-lg"
-            }, /*#__PURE__*/ react.createElement("h3", {
-                className: "text-lg font-semibold mb-2"
-            }, "Something went wrong"), /*#__PURE__*/ react.createElement("p", {
-                className: "text-red-700"
-            }, this.state.error.message), /*#__PURE__*/ react.createElement("button", {
-                onClick: this.handleReset,
-                className: "mt-3 px-4 py-2 text-sm font-medium text-white bg-red-600 rounded hover:bg-red-700 cursor-pointer transition-colors"
-            }, "Try again"));
-        }
-        return this.props.children;
-    }
-}
-function useRemoteModule({ pkg, version, moduleName, scopeName, onError, onLoad, retryKey = 0 }) {
-    const [moduleState, setModuleState] = useState({
-        loading: true,
-        error: null,
-        component: null
-    });
-    useEffect(()=>{
-        let mounted = true;
-        async function loadModule() {
-            try {
-                setModuleState((prev)=>({
-                        ...prev,
-                        loading: true,
-                        error: null
-                    }));
-                const { mf } = await loadRemoteMultiVersion({
-                    name: scopeName,
-                    pkg,
-                    version
-                }, []);
-                if (!mf || !mounted) return;
-                const mod = await mf.loadRemote(`${scopeName}/${moduleName}`);
-                if (!mounted) return;
-                if (mod && 'object' == typeof mod && 'default' in mod) {
-                    const Component = mod.default;
-                    setModuleState({
-                        loading: false,
-                        error: null,
-                        component: Component
-                    });
-                    onLoad?.(Component);
-                } else throw new Error(`Module "${scopeName}/${moduleName}" does not export a default component`);
-            } catch (err) {
-                if (mounted) {
-                    const error = err instanceof Error ? err : new Error(String(err));
-                    setModuleState({
-                        loading: false,
-                        error,
-                        component: null
-                    });
-                    onError?.(error);
-                }
-            }
-        }
-        loadModule();
-        return ()=>{
-            mounted = false;
-        };
-    }, [
-        pkg,
-        version,
-        moduleName,
-        scopeName,
-        onError,
-        onLoad,
-        retryKey
-    ]);
-    return moduleState;
-}
-function RemoteModuleRenderer({ pkg, version, moduleName, scopeName, loadingFallback, errorFallback, componentProps, className, style, onError, onLoad }) {
-    const moduleState = useRemoteModule({
-        pkg,
-        version,
-        moduleName,
-        scopeName,
-        onError,
-        onLoad
-    });
-    const [retryKey, setRetryKey] = useState(0);
-    const handleRetry = useCallback(()=>{
-        setRetryKey((prev)=>prev + 1);
-    }, []);
-    useEffect(()=>{}, [
-        retryKey
-    ]);
-    if (moduleState.loading) return /*#__PURE__*/ react.createElement("div", {
-        className: className,
-        style: style,
-        role: "status",
-        "aria-live": "polite"
-    }, loadingFallback || /*#__PURE__*/ react.createElement("div", {
-        className: "module-card module-card--loading"
-    }, /*#__PURE__*/ react.createElement("div", {
-        className: "loading-spinner",
-        "aria-hidden": "true"
-    }), /*#__PURE__*/ react.createElement("span", {
-        className: "text-gray-600"
-    }, "Loading ", moduleName, "...")));
-    if (moduleState.error) {
-        if ('function' == typeof errorFallback) return /*#__PURE__*/ react.createElement(react.Fragment, null, errorFallback(moduleState.error, handleRetry));
-        if (void 0 !== errorFallback) return /*#__PURE__*/ react.createElement(react.Fragment, null, errorFallback);
-        return /*#__PURE__*/ react.createElement("div", {
-            className: className,
-            style: style,
-            role: "alert"
-        }, /*#__PURE__*/ react.createElement("div", {
-            className: "module-card module-card--error"
-        }, /*#__PURE__*/ react.createElement("span", {
-            className: "error-icon",
-            "aria-hidden": "true"
-        }, "!"), /*#__PURE__*/ react.createElement("span", null, "Failed to load ", moduleName), /*#__PURE__*/ react.createElement("p", {
-            className: "error-message"
-        }, moduleState.error.message), /*#__PURE__*/ react.createElement("button", {
-            onClick: handleRetry,
-            className: "retry-button",
-            type: "button"
-        }, "Retry")));
-    }
-    if (!moduleState.component) return null;
-    const Component = moduleState.component;
-    return /*#__PURE__*/ react.createElement("div", {
-        className: className,
-        style: style
-    }, /*#__PURE__*/ react.createElement(Component, componentProps));
-}
-function RemoteModuleProvider(props) {
-    const { disableErrorBoundary, errorFallback, loadingFallback, errorBoundaryOptions } = props;
-    if (disableErrorBoundary) return /*#__PURE__*/ react.createElement(Suspense, {
-        fallback: loadingFallback || /*#__PURE__*/ react.createElement("div", null, "Loading...")
-    }, /*#__PURE__*/ react.createElement(RemoteModuleRenderer, props));
-    return /*#__PURE__*/ react.createElement(ErrorBoundary, {
-        fallback: errorFallback,
-        onError: errorBoundaryOptions?.onError,
-        onReset: errorBoundaryOptions?.onReset
-    }, /*#__PURE__*/ react.createElement(Suspense, {
-        fallback: loadingFallback || /*#__PURE__*/ react.createElement("div", null, "Loading...")
-    }, /*#__PURE__*/ react.createElement(RemoteModuleRenderer, props)));
-}
-function lazyRemote(options) {
-    const { pkg, version = 'latest', moduleName, scopeName, maxRetries = 3, retryDelay = 1000 } = options;
-    let retryCount = 0;
-    const loadComponent = async ()=>{
-        try {
-            const { mf } = await loadRemoteMultiVersion({
-                name: scopeName,
-                pkg,
-                version
-            }, []);
-            if (!mf) throw new Error(`[RemoteReloadUtils] Failed to get Module Federation instance for ${scopeName}`);
-            const mod = await mf.loadRemote(`${scopeName}/${moduleName}`);
-            if (!mod || 'object' != typeof mod || !('default' in mod)) throw new Error(`[RemoteReloadUtils] Module "${scopeName}/${moduleName}" does not export a default component`);
-            return {
-                default: mod.default
-            };
-        } catch (error) {
-            if (retryCount < maxRetries) {
-                retryCount++;
-                await new Promise((resolve)=>setTimeout(resolve, retryDelay * retryCount));
-                return loadComponent();
-            }
-            throw error;
-        }
-    };
-    return /*#__PURE__*/ lazy(loadComponent);
-}
-function SuspenseRemote({ fallback, children }) {
-    return /*#__PURE__*/ react.createElement(Suspense, {
-        fallback: fallback || /*#__PURE__*/ react.createElement("div", null, "Loading...")
-    }, children);
-}
-function SuspenseRemoteLoader({ pkg, version = 'latest', moduleName, scopeName, fallback, errorFallback, componentProps }) {
-    const RemoteComponent = lazyRemote({
-        pkg,
-        version,
-        moduleName,
-        scopeName
-    });
-    if (errorFallback) return /*#__PURE__*/ react.createElement(ErrorBoundary, {
-        fallback: errorFallback
-    }, /*#__PURE__*/ react.createElement(Suspense, {
-        fallback: fallback || /*#__PURE__*/ react.createElement("div", null, "Loading...")
-    }, /*#__PURE__*/ react.createElement(RemoteComponent, componentProps)));
-    return /*#__PURE__*/ react.createElement(Suspense, {
-        fallback: fallback || /*#__PURE__*/ react.createElement("div", null, "Loading...")
-    }, /*#__PURE__*/ react.createElement(RemoteComponent, componentProps));
-}
-function withRemote(WrappedComponent, options) {
-    const RemoteComponent = lazyRemote(options);
-    return function(props) {
-        return /*#__PURE__*/ react.createElement(Suspense, {
-            fallback: /*#__PURE__*/ react.createElement("div", null, "Loading...")
-        }, /*#__PURE__*/ react.createElement(RemoteComponent, props));
-    };
-}
-function useRemoteModuleHook(options) {
-    const { pkg, version = 'latest', moduleName, scopeName } = options;
-    const [state, setState] = useState({
-        component: null,
-        loading: true,
-        error: null
-    });
-    useEffect(()=>{
-        let mounted = true;
-        async function load() {
-            try {
-                setState((prev)=>({
-                        ...prev,
-                        loading: true,
-                        error: null
-                    }));
-                const { mf } = await loadRemoteMultiVersion({
-                    name: scopeName,
-                    pkg,
-                    version
-                }, []);
-                if (!mf) throw new Error(`[RemoteReloadUtils] Failed to get Module Federation instance for ${scopeName}`);
-                const mod = await mf.loadRemote(`${scopeName}/${moduleName}`);
-                if (mounted) if (mod && 'object' == typeof mod && 'default' in mod) setState({
-                    component: mod.default,
-                    loading: false,
-                    error: null
-                });
-                else throw new Error(`[RemoteReloadUtils] Module "${scopeName}/${moduleName}" does not export a default component`);
-            } catch (err) {
-                if (mounted) setState({
-                    component: null,
-                    loading: false,
-                    error: err instanceof Error ? err : new Error(String(err))
-                });
-            }
-        }
-        load();
-        return ()=>{
-            mounted = false;
-        };
-    }, [
-        pkg,
-        version,
-        moduleName,
-        scopeName
-    ]);
-    return {
-        component: state.component,
-        loading: state.loading,
-        error: state.error
-    };
-}
-export { ErrorBoundary, RemoteModuleProvider, RemoteModuleRenderer, SuspenseRemote, SuspenseRemoteLoader, buildCdnUrls, buildFinalUrls, cancelPreload, checkModuleLoadable, checkRemoteHealth, checkVersionCompatibility, clearPreloadCache, compareVersions, createEventBus, eventBus, extractMajorVersion, fallbackPlugin, fetchAvailableVersions, fetchLatestVersion, findCompatibleVersion, formatHealthStatus, getCompatibleReactVersions, getFinalSharedConfig, getLatestVersion, getLoadedRemotes, getPreloadStatus, getRemoteHealthReport, getStableVersions, getVersionCache, isPrerelease, isRemoteLoaded, lazyRemote, loadReactVersion, loadRemoteMultiVersion, parseVersion, preloadRemote, preloadRemoteList, registerLoadedModule, registerRemoteInstance, resolveFinalVersion, satisfiesVersion, setVersionCache, sortVersions, tryLoadRemote, unloadAll, unloadRemote, useRemoteModule, useRemoteModuleHook, withRemote };
+export { buildCdnUrls, buildFinalUrls, cancelPreload, checkModuleLoadable, checkRemoteHealth, checkVersionCompatibility, clearPreloadCache, compareVersions, createEventBus, createRemoteSourcePlugin, eventBus, extractMajorVersion, fallbackPlugin, fetchAvailableVersions, fetchLatestVersion, findCompatibleVersion, formatHealthStatus, getCompatibleReactVersions, getFinalSharedConfig, getLatestVersion, getLoadedRemotes, getPreloadStatus, getRemoteHealthReport, getStableVersions, getVersionCache, isPrerelease, isRemoteLoaded, loadReactVersion, loadRemoteMultiVersion, parseVersion, preloadRemote, preloadRemoteList, registerLoadedModule, registerRemoteInstance, resolveFinalVersion, satisfiesVersion, setVersionCache, sortVersions, tryLoadRemote, unloadAll, unloadRemote };

package/dist/plugins/register-shared-react.d.ts

@@ -0,0 +1,6 @@
+import type { ModuleFederationRuntimePlugin } from '@module-federation/enhanced/runtime';
+export declare function initSharedScope(): void;
+/**
+ * 注册全局 React/ReactDOM 到 Module Federation 共享作用域
+ */
+export declare const registerSharedReact: () => ModuleFederationRuntimePlugin;

package/dist/types/index.d.ts

@@ -9,7 +9,7 @@ export interface LoadRemoteOptions {
     localFallback?: string;
     cacheTTL?: number;
     revalidate?: boolean;
-    shared?: Record<string, ModuleFederationRuntimePlugin>;
+    shared?: Record<string, any>;
 }
 export interface VersionCache {
     [pkg: string]: {

package/loadRemote.md

@@ -168,7 +168,8 @@ async function loadMultipleComponents() {
 ```typescript
 function loadRemoteMultiVersion(
   options: LoadRemoteOptions,
-  plugins: ModuleFederationRuntimePlugin[]
+  plugins?: ModuleFederationRuntimePlugin[],
+  extraOptions?: LoadRemoteExtraOptions,
 ): Promise<LoadResult>
 ```
 
@@ -192,6 +193,14 @@ function loadRemoteMultiVersion(
 
 Module Federation 运行时插件数组，默认会添加 `fallbackPlugin()`。
 
+**extraOptions**: `LoadRemoteExtraOptions`
+
+| 属性 | 类型 | 必填 | 默认值 | 描述 |
+|------|------|------|--------|------|
+| `baseRemotes` | `RuntimeRemote[]` | ❌ | `[]` | 直接注册的附加 remote 列表 |
+| `remoteSourcePlugins` | `RemoteSourcePlugin[]` | ❌ | `[]` | 通过插件动态返回并注册 remote 列表 |
+| `registerOptions` | `{ force?: boolean }` | ❌ | `{}` | 透传给 `registerRemotes` 的配置 |
+
 #### 返回值
 
 ```typescript
@@ -869,6 +878,38 @@ const { mf } = await loadRemoteMultiVersion(options, [
 ]);
 ```
 
+#### 4. 通过 `registerRemotes` 动态注册多个来源
+
+```typescript
+import { loadRemoteMultiVersion, createRemoteSourcePlugin } from 'remote-reload-utils';
+
+const remoteSourcePlugin = createRemoteSourcePlugin('multi-remote-source', [
+  {
+    name: 'remote_ui_v2',
+    entry: 'https://cdn.example.com/remote-ui-v2/dist/remoteEntry.js',
+  },
+  {
+    name: 'remote_widget',
+    entry: 'https://cdn.example.com/remote-widget/dist/remoteEntry.js',
+  },
+]);
+
+const { scopeName, mf } = await loadRemoteMultiVersion(
+  {
+    name: 'react_mf_lib',
+    pkg: 'test-mf-unpkg',
+    version: 'latest',
+  },
+  [],
+  {
+    remoteSourcePlugins: [remoteSourcePlugin],
+  },
+);
+
+const Button = await mf.loadRemote(`${scopeName}/Button`);
+const Widget = await mf.loadRemote('remote_widget/Widget');
+```
+
 #### 2. 监控加载状态
 
 ```typescript
@@ -1238,7 +1279,31 @@ interface LoadRemoteOptions {
   localFallback?: string;  // 本地兜底
   cacheTTL?: number;  // 缓存时间
   revalidate?: boolean;  // 灰度更新
-  shared?: Record<string, ModuleFederationRuntimePlugin>;  // 自定义 shared 配置
+  shared?: Record<string, any>;  // 自定义 shared 配置
+}
+
+interface LoadRemoteExtraOptions {
+  remoteSourcePlugins?: RemoteSourcePlugin[];
+  baseRemotes?: RuntimeRemote[];
+  registerOptions?: {
+    force?: boolean;
+  };
+}
+
+interface RemoteSourcePluginContext {
+  options: LoadRemoteOptions;
+  scopeName: string;
+  pkg: string;
+  finalVersion: string;
+  currentEntry: string;
+  allEntries: string[];
+}
+
+interface RemoteSourcePlugin {
+  name: string;
+  registerRemotes?: (
+    context: RemoteSourcePluginContext
+  ) => RuntimeRemote[] | void | Promise<RuntimeRemote[] | void>;
 }
 
 interface VersionCache {