企业官网建设流程全解析

如何把React Native嵌入现有iOS/Android应用：Expo Skills的brownfield集成决策指南

【免费下载链接】skillsA collection of AI agent skills for working with Expo projects and Expo Application Services项目地址: https://gitcode.com/gh_mirrors/skills9/skills

👋 如果你正在维护一个原生 iOS 或 Android 应用，又想把 React Native 页面渐进式地嵌进去，这篇文章就是为你准备的。我们将基于 Expo Skills 官方技能库中的expo-brownfield 技能，系统讲解 brownfield 集成决策：隔离（Isolated）与融合（Integrated）两种方案怎么选、版本兼容要点是什么、常见的集成坑又该如何避开。

什么是 brownfield 应用？

Brownfield（棕色地带）指的是一个已经存在的原生 iOS / Android 应用，希望增量引入React Native；与之相对的是greenfield（绿色地带），即从第一天起就是 React Native 项目。

💡 关键原则：保留宿主 App 的入口与原生导航。在手工维护的原生宿主中，不要运行 prebuild 生成原生工程——它会覆盖你精心维护的ios/和android/目录。

在做集成决策之前，先花几分钟"体检"宿主应用：确认入口、导航归属、构建系统（Gradle / CocoaPods / Tuist 等）、部署目标，以及是否已经链接过 React Native 运行时。

两种嵌入方式：Isolated 还是 Integrated？

Expo 支持两种把 React Native 加进 brownfield 项目的方式，核心区别在于交付物和构建体系的影响面：

📦 Isolated：把 React Native 打成预构建库

• React Native + Expo 代码构建为 Android 的AAR、iOS 的XCFramework，原生应用像依赖普通第三方库一样消费它。
• 发布构建中JS bundle 已内嵌在 artifact 里，生产环境运行时不需要 Metro。
• 原生团队零 Node、零 Yarn，即使团队用 Tuist 或定制 Gradle 也无感。
• 想要"随时低成本拆掉 React Native"？删除依赖即可，原生构建几乎不受影响。

🧩 Integrated：直接融入 Gradle / CocoaPods

• 把 React Native + Expo 直接加进现有原生项目的构建体系，享受 Expo 模块自动链接（autolinking）。
• 一次构建、一条流水线，适合"一个团队、一个仓库、深度集成"的场景。
• 代价：构建体系侵入较大，RN 版本升级需要与原生构建协同。

完整决策矩阵见 references/comparison.md。

快速决策的 5 条黄金法则 🧭

来自 expo-brownfield 技能主文档的决策规则，遇到模糊情况直接对号入座：

1. 选 Isolated：原生团队必须以常规库依赖（AAR / XCFramework）方式消费 React Native，不装任何 JS 工具链。
2. 选 Isolated：RN 代码与原生代码在不同仓库，或发布节奏互相独立。
3. 选 Isolated：原生构建体系高度定制（Tuist、Bazel、自定义 Gradle 插件），不希望引入 RN Gradle 插件。
4. 选 Integrated：单一团队同时拥有原生和 RN 代码，愿意在原生项目中维护 RN 构建链。
5. 别被热更新误导：两种方式都支持 Metro + Fast Refresh。选择 Integrated 的理由是"共享构建归属"，而不是"Isolated 不能热刷新"。

⚖️ 拿不准时——尤其是当问题变成"原生团队能不能不碰 React Native 工具链？"——选 Isolated。

动手前的版本兼容性检查 ✅

• Isolated 方案要求 Expo SDK 55+（expo-brownfield包自 SDK 55 引入），且构建 artifact 的环境需要Node.js (LTS)和项目现有的包管理器。
• 已有 Expo 项目：保持其 SDK 版本，用npx expo install对齐依赖，不要为了"跟教程走"而强行升级。
• 新建 producer 项目：选用与宿主系统支持、依赖和构建工具链匹配的当前稳定 SDK。
• 原生侧改动前，务必先读 version-compatibility.md，核对各 SDK 版本对应的原生模板、工具链和系统最低要求。

最小命令示例（Isolated 方案的 producer 侧）：

npx create-expo-app@latest my-project --template blank@latest cd my-project npx expo install expo-brownfield

避坑指南：集成中最常见的 3 类问题 🛠️

完整清单见 references/troubleshooting.md，这里挑最高频的三类：

1. Metro 连不上（Debug 红屏）

• 确认设备能访问开发机：Android 模拟器可用10.0.2.2，真机需同一局域网；USB 真机用adb reverse tcp:8081 tcp:8081。
• Android 9+ 默认禁止 HTTP，Debug 变体需要开启 cleartext 流量。
• iOS 模拟器需保留Info.plist中对localhost的 ATS 例外。

2. "Native module cannot be null"

• 新模块要用npx expo install安装（而非裸yarn add），它会自动挑选与当前 SDK 兼容的版本。
• 自动链接发生在原生构建时，装完新模块要重新构建原生应用。
• Isolated 方案装完新模块后，必须重跑npx expo-brownfield build:android/build:ios并重新分发 artifact。

3. iOS XCFramework 签名崩溃（"Library not loaded"）

• 检查生成的Package.swift和实际输出，确保所有必需的动态 framework 都链接并嵌入到app target（不是 extension target），且不要对静态库做 Embed & Sign。
• 遇到 "building for simulator but linked for iOS" 一类架构错误，重新构建缺失平台即可；expo-brownfield build:ios默认同时产出真机与模拟器切片。

集成完成 ≠ 能跑：验收清单 📋

在 Expo Go 或 producer 示例应用里能渲染，不代表集成成功。真正的验收场景（来自 references/feature-integration.md）：

1. 带着初始输入打开 RN 屏幕；
2. RN 向原生返回结果，原生正确接收；
3. 关闭屏幕，再次打开时传入全新输入；
4. 检查监听器是否被正确清理，宿主的原生导航是否完好；
5. 关闭 Metro，用 Release artifact 构建宿主，全流程再走一遍。

仓库里还有一组可运行的 iOS 测试夹具，覆盖 Isolated 与 Integrated 两种宿主、SDK 55 / 57 两个版本，验收清单直接可照抄，见 tests/fixtures/expo-brownfield/README.md：

参考资料导航 📚

写在最后

一句话总结决策逻辑：团队边界清晰、想隔离风险 → Isolated；单一团队、追求统一构建 → Integrated。Expo Skills 的 expo-brownfield 技能把这两条路的完整细节——从版本对齐、依赖审计到验收清单——都整理成了可直接执行的参考文档。把它交给你的 AI 编程助手，剩下的就是按图索骥了。🚀

【免费下载链接】skillsA collection of AI agent skills for working with Expo projects and Expo Application Services项目地址: https://gitcode.com/gh_mirrors/skills9/skills