深入解析 install-expo-modules让既有 React Native 项目平滑接入 Expo Modules【免费下载链接】expoAn open-source framework for making universal native apps with React. Expo runs on Android, iOS, and the web.项目地址: https://gitcode.com/GitHub_Trending/ex/expoinstall-expo-modules是 expo/expo 仓库中专门服务于存量 React Native 项目的迁移工具只需在项目根目录执行一条npx install-expo-modules命令它就会自动安装expo核心包、修改 Android/iOS 原生工程与 Babel/Metro 配置让纯 React NativeRNC CLI项目无缝获得 expo-modules 与 Expo SDK 的能力。读完本文你将掌握该工具的使用方式、背后 SDK 版本映射与原生工程改写机制并了解其版本演进脉络与贡献方法。一、工具定位与快速上手根据 packages/install-expo-modules/README.md该工具面向已经存在的 React Native 项目帮助其更轻松地采用 expo-modules 与 Expo SDK。使用方式极其简单——在项目根目录执行npx install-expo-modules执行完成后就可以通过expo install安装你需要的具体 expo 模块例如expo install expo-device # 注意expo 命令来自 expo-cli若未安装可先执行 npm -g install expo-cli工具的核心入口位于 src/index.tsCLI 基于commander构建其可用的命令行参数包括参数说明[project-directory]目标项目目录缺省时使用当前工作目录process.cwd()-s, --sdk-version version指定要安装的 Expo SDK 版本不指定则根据项目 React Native 版本自动推导--non-interactive禁用交互式确认提示适用于 CI 等自动化场景二、工具为项目做了什么README 明确列出了install-expo-modules完成的工作清单结合 src/index.ts 的runAsync主流程实际执行链路如下定位项目根目录并探测平台normalizeProjectRootAsync会向上查找package.json确定项目根目录并检测是否存在android/ios目录来决定要改写的平台见 src/utils/projectRoot.ts。安装expo包安装必要的核心包并启用 react-native 自动链接autolinking为后续模块安装打好基础见 src/utils/packageInstaller.ts 的installExpoPackageAsync它会优先安装正式发布版本失败时回退到预发布版本范围。修改项目文件以适配 expo-modules如果项目由 git 管理完全可以用git diff审查工具所做的每一项改动做到所见即所得。升级 iOS 部署目标由于 expo-modules 的最低 iOS 版本要求可能高于 React Native 核心当现有部署目标偏低时工具会自动将其提升。最后执行pod install为 iOS 更新链接的模块。从源码看这一步只在process.platform darwinmacOS上执行与 CHANGELOG 中 0.14.19 的Skip pods install on non-darwin platforms改动相对应。整个过程通过expo/config-plugins的compileModsAsync编译配置修改器mods完成执行顺序是先改写工程文件、再安装 npm 包、最后装 Pods。三、核心机制SDK 版本映射表工具最关键的机制是Expo SDK 与 React Native 版本之间的映射定义在 src/utils/expoVersionMappings.ts 的ExpoVersionMappings数组中。每个条目包含expoPackageVersion要安装的exponpm 包版本范围sdkVersion对应的 Expo SDK 版本号iosDeploymentTarget该 SDK 要求的最低 iOS 部署目标reactNativeVersionRange兼容的 React Native 版本范围semver 表达式androidAgpVersion可选最低 Android Gradle Plugin 版本要求supportCliIntegration可选是否支持 Expo CLI 集成。当前映射表内容截至仓库中 0.16.0 版本Expo SDKexpo 包版本RN 版本范围最低 iOS 目标56.0.0~56.0.0~0.85.016.455.0.0~55.0.0~0.83.015.154.0.0~54.0.0~0.81.015.153.0.0~53.0.0~0.79.015.152.0.0~52.0.0 0.76.0 0.78.015.151.0.0~51.0.0 0.74.0 0.76.013.450.0.0~50.0.0~0.73.013.449.0.0~49.0.0~0.72.013.048.0.0~48.0.0~0.71.013.0AGP 7.4.147.0.0~47.0.0~0.70.013.046.0.0~46.0.0~0.69.012.445.0.0~45.0.0 0.65.0 0.69.012.044.0.0~44.0.0 0.68.012.043.0.0~43.0.0 0.68.012.0当未通过-s指定 SDK 版本时getDefaultSdkVersion会读取项目react-native/package.json的实际版本用semver.satisfies与映射表匹配自动选择兼容的 SDK找不到时会抛出明确的错误提示。这种以 RN 版本反推 SDK的设计正是工具能对存量项目做到零配置迁移的关键。四、Android 侧工程改写细节在 Android 平台上工具通过多个 config plugin 完成原生代码改造1. settings.gradle 自动链接src/plugins/android/withAndroidSettingsGradle.ts 会在pluginManagement中注入expo-modules-autolinking的解析逻辑与includeBuild注册expo-autolinking-settings插件并将ex.autolinkLibrariesFromCommand()改写为ex.autolinkLibrariesFromCommand(expoAutolinking.rnConfigCommand)最后追加useExpoModules()、useExpoVersionCatalog()与includeBuild(expoAutolinking.reactNativeGradlePlugin)。对于 SDK 53 之前的项目则走另一套基于autolinking.gradle脚本的兼容路径见文件中的updateAndroidSettingsGradleSdk52。2. MainApplication 改造src/plugins/android/withAndroidModulesMainApplication.ts 展示了工具对MainApplication的精细化改写逻辑且能同时处理 Java 与 Kotlin为DefaultReactNativeHostRN ≥ 0.71与ReactNativeHost实例注入ReactNativeHostWrapper包装SDK ≥ 55 时将getDefaultReactHost()替换为ExpoReactHostFactory.getDefaultReactHost()SDK 51–54 则替换为ReactNativeHostWrapper.createReactHost()注入ApplicationLifecycleDispatcher的onApplicationCreate调用并在缺失时补全onConfigurationChanged重写确保 Expo 模块能感知应用生命周期与配置变化。3. 构建脚本与 AGP 版本src/plugins/android/withAndroidGradles.ts 负责 Gradle 版本相关调整。从 src/index.ts 可以看到当检测到项目 AGP 版本低于 Expo 模块要求时工具会弹出确认提示--non-interactive模式下直接以黄色警告输出并继续确认后才将 AGP 提升到要求版本。iOS 部署目标升级也采用同样的交互模式两条提示分别对应withAndroidGradlePluginVersion与withIosDeploymentTarget。五、iOS 侧工程改写细节iOS 平台同样由一系列插件驱动AppDelegate 改造见 src/plugins/ios/withIosModulesAppDelegate.ts。该插件同时支持 Objective-C/ObjC 与 Swift 三种语言形态ObjC 工程会把父类替换为EXAppDelegateWrapper并补全[super application:...]调用与Expo/Expo.h导入Swift 工程则根据 SDK 版本选择不同的改造策略——SDK 52 使用ExpoModulesCore中的ExpoAppDelegateSDK 55 进一步使用internal import Expo以兼容 Swift 6并替换RCTReactNativeFactory/RCTDefaultReactNativeFactoryDelegate为 Expo 对应类。Podfile 处理withIosModulesPodfile.ts 负责注入 Expo 相关 pod 配置。Swift 版本与部署目标withSwiftVersion统一将 Swift 版本设置为 5.0withIosDeploymentTarget按映射表提升部署目标。Xcode 工程解析通过xcparse见 withXCParseXcodeProject.ts直接解析.pbxproj用于查找 Swift bridging header 文件引用、扫描PBXShellScriptBuildPhase等这也是 0.14.19 之前 CHANGELOG 中多次修复 Xcode 工程问题的底层技术。六、可选的 Expo CLI 集成工具会在交互模式下询问是否安装 Expo CLI 集成见 src/index.ts 的promptCliIntegrationAsync推荐启用否则部分功能可能无法按预期工作。选择启用后src/plugins/cli/withCliIntegration.ts 会通过withPlugins依次执行六项子改动改写app/build.gradle仅支持 groovy 语法为 AndroidMainApplication与 iOSAppDelegate设置虚拟的 Metro 入口在 Xcode 工程的PBXShellScriptBuildPhase中加入 Expo 相关脚本更新 Babel 配置以使用babel-preset-expo找不到配置文件时给出警告更新 Metro 配置并处理.gitignore。若启用 CLI 集成还会额外安装babel-preset-expo见 packageInstaller.ts 的installBabelPresetExpoNonInteractiveAsync。七、版本演进时间线来自 CHANGELOGpackages/install-expo-modules/CHANGELOG.md 完整记录了该工具的演进历程从中可以清晰地看到它与 Expo SDK / React Native 版本同步的节奏2024 年0.7.0–0.10.2包从expo/expo-cli迁移到expo/expo仓库0.7.0加入 Expo SDK 50 / RN 0.73 支持0.8.0修复 CNG 项目上的ENOENT误报与 Yarn v3 语法错误、避免在npx install-expo-modules时重复安装依赖0.8.1加入 SDK 51 / RN 0.74 支持0.10.0。2024 年底0.11.x0.11.0 将 iOS 部署目标提升至 15.1支持除babel.config.js外的其他 Babel 配置文件名、加入 RN 0.76 支持并修复 RNC CLI 项目的 Unsupported Swift Version 问题与缺失babel.config.js时的崩溃。2025 年0.12.x–0.13.x0.12.0 一次性加入 RN 0.77/0.78/0.79 支持0.12.3 更新了 SDK 53 的AppDelegate.swift改造逻辑0.13.10 加入 RN 0.81 与 SDK 54 支持0.13.13 将glob升级到 v13。2026 年0.14.x–0.16.00.14.0 起进入高频维护期0.14.5 允许 React Native TV 项目使用0.14.10/0.14.11 加入 SDK 55 / RN 0.83 支持0.14.19 将最低 iOS/tvOS 版本提升至 16.4、macOS 提升至 13.4并在非 darwin 平台跳过 pods 安装0.15.0 升级expo/spawn-async未发布的版本还包含对偶发ncc构建失败的修复。从 0.16.0 之后的多条 no user-facing changes 记录可以看出工具在功能稳定后进入了以依赖维护为主的状态。这条时间线同时也回答了我的 React Native 版本能不能用的问题由于映射表持续更新从 RN 0.65 时代的老项目到 0.85 的新项目都能找到对应的 SDK 版本。八、测试保障与贡献方式工具的每个改写插件都配有单元测试与 fixture 对照文件例如Android 侧MainActivity/MainApplication的 Java/Kotlin fixture 覆盖了 RN 0.64、0.68、0.71、0.73、0.74、0.83 等不同版本形态见 plugins/android/testsiOS 侧AppDelegate的.m/.mm/.h/.swift与 Podfile fixture 覆盖 RN 0.67–0.83 各代工程见 plugins/ios/testsCLI 集成侧通过 snapshot 测试校验AppDelegate、MainApplication、gradle、Babel、Metro 与.pbxproj的完整改写结果见 plugins/cli/tests。SDK 版本映射也有专门的测试utils/tests/expoVersionMappings-test.ts。若你希望为本工具贡献改动README 给出了推荐流程先在仓库内运行pnpm watch以监听模式构建改动后在一个 RNC CLI 测试项目里执行node path_to_expo/packages/install-expo-modules/bin/install-expo-modules.js .验证并记得为改动补充单元测试。九、小结install-expo-modules通过SDK 版本映射表 config-plugins 工程改写 交互式确认三件套把原本繁琐、易错的手工迁移变成了可复现、可审查的一键操作。无论是老项目想要用上 Expo 生态的模块还是团队希望统一到 Expo SDK 的管理方式这条迁移路径都值得优先考虑执行一条命令用git diff审查改动再用expo install按需添加模块即可完成从纯 React Native 到 expo-modules 的平滑过渡。【免费下载链接】expoAn open-source framework for making universal native apps with React. Expo runs on Android, iOS, and the web.项目地址: https://gitcode.com/GitHub_Trending/ex/expo创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 深入解析 install-expo-modules：让既有 React Native 项目平滑接入 Expo Modules
深入解析 install-expo-modules让既有 React Native 项目平滑接入 Expo Modules【免费下载链接】expoAn open-source framework for making universal native apps with React. Expo runs on Android, iOS, and the web.项目地址: https://gitcode.com/GitHub_Trending/ex/expoinstall-expo-modules是 expo/expo 仓库中专门服务于存量 React Native 项目的迁移工具只需在项目根目录执行一条npx install-expo-modules命令它就会自动安装expo核心包、修改 Android/iOS 原生工程与 Babel/Metro 配置让纯 React NativeRNC CLI项目无缝获得 expo-modules 与 Expo SDK 的能力。读完本文你将掌握该工具的使用方式、背后 SDK 版本映射与原生工程改写机制并了解其版本演进脉络与贡献方法。一、工具定位与快速上手根据 packages/install-expo-modules/README.md该工具面向已经存在的 React Native 项目帮助其更轻松地采用 expo-modules 与 Expo SDK。使用方式极其简单——在项目根目录执行npx install-expo-modules执行完成后就可以通过expo install安装你需要的具体 expo 模块例如expo install expo-device # 注意expo 命令来自 expo-cli若未安装可先执行 npm -g install expo-cli工具的核心入口位于 src/index.tsCLI 基于commander构建其可用的命令行参数包括参数说明[project-directory]目标项目目录缺省时使用当前工作目录process.cwd()-s, --sdk-version version指定要安装的 Expo SDK 版本不指定则根据项目 React Native 版本自动推导--non-interactive禁用交互式确认提示适用于 CI 等自动化场景二、工具为项目做了什么README 明确列出了install-expo-modules完成的工作清单结合 src/index.ts 的runAsync主流程实际执行链路如下定位项目根目录并探测平台normalizeProjectRootAsync会向上查找package.json确定项目根目录并检测是否存在android/ios目录来决定要改写的平台见 src/utils/projectRoot.ts。安装expo包安装必要的核心包并启用 react-native 自动链接autolinking为后续模块安装打好基础见 src/utils/packageInstaller.ts 的installExpoPackageAsync它会优先安装正式发布版本失败时回退到预发布版本范围。修改项目文件以适配 expo-modules如果项目由 git 管理完全可以用git diff审查工具所做的每一项改动做到所见即所得。升级 iOS 部署目标由于 expo-modules 的最低 iOS 版本要求可能高于 React Native 核心当现有部署目标偏低时工具会自动将其提升。最后执行pod install为 iOS 更新链接的模块。从源码看这一步只在process.platform darwinmacOS上执行与 CHANGELOG 中 0.14.19 的Skip pods install on non-darwin platforms改动相对应。整个过程通过expo/config-plugins的compileModsAsync编译配置修改器mods完成执行顺序是先改写工程文件、再安装 npm 包、最后装 Pods。三、核心机制SDK 版本映射表工具最关键的机制是Expo SDK 与 React Native 版本之间的映射定义在 src/utils/expoVersionMappings.ts 的ExpoVersionMappings数组中。每个条目包含expoPackageVersion要安装的exponpm 包版本范围sdkVersion对应的 Expo SDK 版本号iosDeploymentTarget该 SDK 要求的最低 iOS 部署目标reactNativeVersionRange兼容的 React Native 版本范围semver 表达式androidAgpVersion可选最低 Android Gradle Plugin 版本要求supportCliIntegration可选是否支持 Expo CLI 集成。当前映射表内容截至仓库中 0.16.0 版本Expo SDKexpo 包版本RN 版本范围最低 iOS 目标56.0.0~56.0.0~0.85.016.455.0.0~55.0.0~0.83.015.154.0.0~54.0.0~0.81.015.153.0.0~53.0.0~0.79.015.152.0.0~52.0.0 0.76.0 0.78.015.151.0.0~51.0.0 0.74.0 0.76.013.450.0.0~50.0.0~0.73.013.449.0.0~49.0.0~0.72.013.048.0.0~48.0.0~0.71.013.0AGP 7.4.147.0.0~47.0.0~0.70.013.046.0.0~46.0.0~0.69.012.445.0.0~45.0.0 0.65.0 0.69.012.044.0.0~44.0.0 0.68.012.043.0.0~43.0.0 0.68.012.0当未通过-s指定 SDK 版本时getDefaultSdkVersion会读取项目react-native/package.json的实际版本用semver.satisfies与映射表匹配自动选择兼容的 SDK找不到时会抛出明确的错误提示。这种以 RN 版本反推 SDK的设计正是工具能对存量项目做到零配置迁移的关键。四、Android 侧工程改写细节在 Android 平台上工具通过多个 config plugin 完成原生代码改造1. settings.gradle 自动链接src/plugins/android/withAndroidSettingsGradle.ts 会在pluginManagement中注入expo-modules-autolinking的解析逻辑与includeBuild注册expo-autolinking-settings插件并将ex.autolinkLibrariesFromCommand()改写为ex.autolinkLibrariesFromCommand(expoAutolinking.rnConfigCommand)最后追加useExpoModules()、useExpoVersionCatalog()与includeBuild(expoAutolinking.reactNativeGradlePlugin)。对于 SDK 53 之前的项目则走另一套基于autolinking.gradle脚本的兼容路径见文件中的updateAndroidSettingsGradleSdk52。2. MainApplication 改造src/plugins/android/withAndroidModulesMainApplication.ts 展示了工具对MainApplication的精细化改写逻辑且能同时处理 Java 与 Kotlin为DefaultReactNativeHostRN ≥ 0.71与ReactNativeHost实例注入ReactNativeHostWrapper包装SDK ≥ 55 时将getDefaultReactHost()替换为ExpoReactHostFactory.getDefaultReactHost()SDK 51–54 则替换为ReactNativeHostWrapper.createReactHost()注入ApplicationLifecycleDispatcher的onApplicationCreate调用并在缺失时补全onConfigurationChanged重写确保 Expo 模块能感知应用生命周期与配置变化。3. 构建脚本与 AGP 版本src/plugins/android/withAndroidGradles.ts 负责 Gradle 版本相关调整。从 src/index.ts 可以看到当检测到项目 AGP 版本低于 Expo 模块要求时工具会弹出确认提示--non-interactive模式下直接以黄色警告输出并继续确认后才将 AGP 提升到要求版本。iOS 部署目标升级也采用同样的交互模式两条提示分别对应withAndroidGradlePluginVersion与withIosDeploymentTarget。五、iOS 侧工程改写细节iOS 平台同样由一系列插件驱动AppDelegate 改造见 src/plugins/ios/withIosModulesAppDelegate.ts。该插件同时支持 Objective-C/ObjC 与 Swift 三种语言形态ObjC 工程会把父类替换为EXAppDelegateWrapper并补全[super application:...]调用与Expo/Expo.h导入Swift 工程则根据 SDK 版本选择不同的改造策略——SDK 52 使用ExpoModulesCore中的ExpoAppDelegateSDK 55 进一步使用internal import Expo以兼容 Swift 6并替换RCTReactNativeFactory/RCTDefaultReactNativeFactoryDelegate为 Expo 对应类。Podfile 处理withIosModulesPodfile.ts 负责注入 Expo 相关 pod 配置。Swift 版本与部署目标withSwiftVersion统一将 Swift 版本设置为 5.0withIosDeploymentTarget按映射表提升部署目标。Xcode 工程解析通过xcparse见 withXCParseXcodeProject.ts直接解析.pbxproj用于查找 Swift bridging header 文件引用、扫描PBXShellScriptBuildPhase等这也是 0.14.19 之前 CHANGELOG 中多次修复 Xcode 工程问题的底层技术。六、可选的 Expo CLI 集成工具会在交互模式下询问是否安装 Expo CLI 集成见 src/index.ts 的promptCliIntegrationAsync推荐启用否则部分功能可能无法按预期工作。选择启用后src/plugins/cli/withCliIntegration.ts 会通过withPlugins依次执行六项子改动改写app/build.gradle仅支持 groovy 语法为 AndroidMainApplication与 iOSAppDelegate设置虚拟的 Metro 入口在 Xcode 工程的PBXShellScriptBuildPhase中加入 Expo 相关脚本更新 Babel 配置以使用babel-preset-expo找不到配置文件时给出警告更新 Metro 配置并处理.gitignore。若启用 CLI 集成还会额外安装babel-preset-expo见 packageInstaller.ts 的installBabelPresetExpoNonInteractiveAsync。七、版本演进时间线来自 CHANGELOGpackages/install-expo-modules/CHANGELOG.md 完整记录了该工具的演进历程从中可以清晰地看到它与 Expo SDK / React Native 版本同步的节奏2024 年0.7.0–0.10.2包从expo/expo-cli迁移到expo/expo仓库0.7.0加入 Expo SDK 50 / RN 0.73 支持0.8.0修复 CNG 项目上的ENOENT误报与 Yarn v3 语法错误、避免在npx install-expo-modules时重复安装依赖0.8.1加入 SDK 51 / RN 0.74 支持0.10.0。2024 年底0.11.x0.11.0 将 iOS 部署目标提升至 15.1支持除babel.config.js外的其他 Babel 配置文件名、加入 RN 0.76 支持并修复 RNC CLI 项目的 Unsupported Swift Version 问题与缺失babel.config.js时的崩溃。2025 年0.12.x–0.13.x0.12.0 一次性加入 RN 0.77/0.78/0.79 支持0.12.3 更新了 SDK 53 的AppDelegate.swift改造逻辑0.13.10 加入 RN 0.81 与 SDK 54 支持0.13.13 将glob升级到 v13。2026 年0.14.x–0.16.00.14.0 起进入高频维护期0.14.5 允许 React Native TV 项目使用0.14.10/0.14.11 加入 SDK 55 / RN 0.83 支持0.14.19 将最低 iOS/tvOS 版本提升至 16.4、macOS 提升至 13.4并在非 darwin 平台跳过 pods 安装0.15.0 升级expo/spawn-async未发布的版本还包含对偶发ncc构建失败的修复。从 0.16.0 之后的多条 no user-facing changes 记录可以看出工具在功能稳定后进入了以依赖维护为主的状态。这条时间线同时也回答了我的 React Native 版本能不能用的问题由于映射表持续更新从 RN 0.65 时代的老项目到 0.85 的新项目都能找到对应的 SDK 版本。八、测试保障与贡献方式工具的每个改写插件都配有单元测试与 fixture 对照文件例如Android 侧MainActivity/MainApplication的 Java/Kotlin fixture 覆盖了 RN 0.64、0.68、0.71、0.73、0.74、0.83 等不同版本形态见 plugins/android/testsiOS 侧AppDelegate的.m/.mm/.h/.swift与 Podfile fixture 覆盖 RN 0.67–0.83 各代工程见 plugins/ios/testsCLI 集成侧通过 snapshot 测试校验AppDelegate、MainApplication、gradle、Babel、Metro 与.pbxproj的完整改写结果见 plugins/cli/tests。SDK 版本映射也有专门的测试utils/tests/expoVersionMappings-test.ts。若你希望为本工具贡献改动README 给出了推荐流程先在仓库内运行pnpm watch以监听模式构建改动后在一个 RNC CLI 测试项目里执行node path_to_expo/packages/install-expo-modules/bin/install-expo-modules.js .验证并记得为改动补充单元测试。九、小结install-expo-modules通过SDK 版本映射表 config-plugins 工程改写 交互式确认三件套把原本繁琐、易错的手工迁移变成了可复现、可审查的一键操作。无论是老项目想要用上 Expo 生态的模块还是团队希望统一到 Expo SDK 的管理方式这条迁移路径都值得优先考虑执行一条命令用git diff审查改动再用expo install按需添加模块即可完成从纯 React Native 到 expo-modules 的平滑过渡。【免费下载链接】expoAn open-source framework for making universal native apps with React. Expo runs on Android, iOS, and the web.项目地址: https://gitcode.com/GitHub_Trending/ex/expo创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考