简体中文

Metro

Metro 模块联邦（Module Federation）为 React Native 移动开发带来了分布式架构的能力。

概述

React Native 的模块联邦实现使用了自定义的 Metro 打包器集成，能够实现：

微前端架构 —— 在 React Native 应用中实现微前端
代码共享 —— 在多个 React Native 应用之间共享代码
独立部署 —— 各个应用模块可以独立部署
运行时模块加载 —— 支持动态更新

注意：Metro 打包器的模块联邦支持仍处于实验阶段，可能缺少部分功能或集成。依赖自定义 Metro 配置的项目或库目前尚不支持，可能无法正常工作。

包

React Native 模块联邦生态系统由以下几个包组成：

@module-federation/metro - 与 Metro 的核心集成，用于启用模块联邦
@module-federation/metro-plugin-rnc-cli - React Native CLI 集成
@module-federation/metro-plugin-rnef - React Native Enterprise Framework 集成

安装

在 React Native 项目中安装所需的包（使用你喜欢的包管理器）：

# 核心包（必需）
pnpm add @module-federation/metro

# 如果项目使用 React Native CLI
pnpm add @module-federation/metro-plugin-rnc-cli

# 如果项目使用 React Native Enterprise Framework (RNEF)
pnpm add @module-federation/metro-plugin-rnef

配置

使用 withModuleFederation 包装你的 Metro 配置以启用模块联邦。
你需要在所有联邦模块（宿主应用和子应用）的 Metro 配置中使用该方法。

const { withModuleFederation } = require('@module-federation/metro');
const { getDefaultConfig, mergeConfig } = require('@react-native/metro-config');

const config = {};

module.exports = withModuleFederation(
  mergeConfig(getDefaultConfig(__dirname), config),
  {
    // 模块联邦配置遵循官方文档格式：
    // https://module-federation.io/configure/index.html
    // 注意：部分功能在 React Native 环境中可能不可用
    name: 'YourAppName',
    remotes: {
      // 定义远程应用（用于宿主应用）
      // remoteName: 'remoteName@http://localhost:8082/mf-manifest.json',
    },
    exposes: {
      // 暴露模块（用于远程应用）
      // './Component': './src/Component.tsx',
    },
    shared: {
      // 宿主应用应为所有共享依赖设置 eager: true
      react: {
        singleton: true,
        eager: true,
        requiredVersion: '19.1.0',
        version: '19.1.0',
      },
      'react-native': {
        singleton: true,
        eager: true,
        requiredVersion: '0.80.0',
        version: '0.80.0',
      },
    },
  },
  {
    // 这些实验性标志用于修补旧版本包
    // 如果项目使用受支持的 React Native 和 Metro 版本，可以省略
    flags: {
      // 启用修补 React Native 的 HMR Client
      unstable_patchHMRClient: true,
      // 启用修补 React Native CLI
      unstable_patchInitializeCore: true,
      // 启用修补 Metro 的运行时 require
      unstable_patchRuntimeRequire: true,
    },
  }
);

应用异步边界设置

使用 withAsyncStartup 包装主 App 组件以启用模块联邦运行时。
这会创建一个异步边界，确保在渲染应用组件之前正确初始化模块联邦运行时。

import { withAsyncStartup } from '@module-federation/runtime';
import { AppRegistry } from 'react-native';

// 使用 withAsyncStartup 创建异步边界
// 传入获取 App 组件的函数
// 可选地传入获取备用组件的函数
const WrappedApp = withAsyncStartup(
  () => require('./App'),
  () => require('./Fallback') // 可选备用组件
);

AppRegistry.registerComponent('YourAppName', WrappedApp);

withAsyncStartup 的作用：

在渲染应用前等待模块联邦运行时初始化
使用 React Suspense 处理异步加载
可选地接受一个备用组件，在初始化期间显示

使用模式

宿主应用

宿主应用从其他应用中消费远程模块：

// 宿主应用 metro.config.js
module.exports = withModuleFederation(
  mergeConfig(getDefaultConfig(__dirname), config),
  {
    name: 'HostApp',
    remotes: {
      'mini-app': 'miniApp@http://localhost:8082/mf-manifest.json',
      'another-app': 'anotherApp@http://192.168.1.100:8083/mf-manifest.json',
    },
    shared: {
      react: { singleton: true, eager: true },
      'react-native': { singleton: true, eager: true },
    },
  }
);

远程应用（子应用）

远程应用暴露模块供宿主应用使用：

// 远程应用 metro.config.js
module.exports = withModuleFederation(
  mergeConfig(getDefaultConfig(__dirname), config),
  {
    name: 'MiniApp',
    exposes: {
      './Screen': './src/Screen.tsx',
      './Component': './src/Component.tsx',
    },
    shared: {
      react: { singleton: true, eager: true },
      'react-native': { singleton: true, eager: true },
    },
  }
);

CLI 命令

React Native CLI 集成提供了额外的命令来打包联邦应用：

打包宿主应用

打包消费远程模块的宿主应用：

# iOS 打包
react-native bundle-mf-host --entry-file index.js --platform ios

# Android 打包
react-native bundle-mf-host --entry-file index.js --platform android

打包远程应用

打包暴露模块的远程应用（子应用）：

# iOS 打包
react-native bundle-mf-remote --platform ios

# Android 打包
react-native bundle-mf-remote --platform android

这些命令支持与标准 react-native bundle 命令相同的所有选项。

注意：这些命令由 @module-federation/metro-plugin-rnc-cli 包提供。

React Native Enterprise Framework (RNEF) 集成

如果项目使用 React Native Enterprise Framework (RNEF)，请在 rnef.config.mjs 中添加模块联邦插件：

import { pluginMetroModuleFederation } from '@module-federation/metro-plugin-rnef';
import { platformAndroid } from '@rnef/platform-android';
import { platformIOS } from '@rnef/platform-ios';
import { pluginMetro } from '@rnef/plugin-metro';

/** @type {import('@rnef/config').Config} */
export default {
  bundler: pluginMetro(),
  platforms: {
    ios: platformIOS(),
    android: platformAndroid(),
  },
  plugins: [pluginMetroModuleFederation()],
};

API 参考

`withModuleFederation(metroConfig, federationConfig, options?)`

包装 Metro 配置以启用模块联邦。

参数

metroConfig (MetroConfig) - 现有的 Metro 配置
federationConfig (FederationConfig) - 模块联邦配置
options (Options) - 可选配置，用于实验性功能

FederationConfig 接口

export interface ModuleFederationConfig {
  name: string;
  filename?: string;
  remotes?: Record<string, string>;
  exposes?: Record<string, string>;
  shared?: Shared;
  shareStrategy?: 'loaded-first' | 'version-first';
  plugins?: string[];
}

SharedConfig 接口

export interface SharedConfig {
  singleton: boolean;
  eager: boolean;
  version: string;
  requiredVersion: string;
  import?: false;
}

示例与最佳实践

配置遵循标准的模块联邦配置格式。
关于模块联邦的概念、配置选项和使用模式的完整信息，请参考官方模块联邦文档。

要查看可运行的示例和详细实现指南，请访问 Module Federation Metro 仓库，其中包含多个示例应用，展示了不同的使用模式和集成方式。

#Metro

#概述

#包

#安装

#配置

#应用异步边界设置

#使用模式

#宿主应用

#远程应用（子应用）

#CLI 命令

#打包宿主应用

#打包远程应用

#React Native Enterprise Framework (RNEF) 集成

#API 参考

#withModuleFederation(metroConfig, federationConfig, options?)

#参数

#FederationConfig 接口

#SharedConfig 接口

#示例与最佳实践