expo-brownfield

Expo Brownfield

Brownfield 应用是指在现有原生 iOS 或 Android 应用中逐步采用 React Native 的应用；而 Greenfield 应用则从第一天起就使用 React Native。

先检查宿主应用

确定现有应用的入口点、导航归属方、原生构建系统、部署目标，以及是否已链接 React Native 运行时。从锁文件中记录已安装的 Expo、React Native 和 Brownfield 软件包版本。仅向 Swift 应用添加 EAS Build 或 Submit 并不需要 React Native；应将此类任务交给 eas-app-stores。

嵌入功能时，请保留宿主应用的 SwiftUI App / UIKit 窗口和原生屏幕。请勿在手动维护的原生宿主应用中运行 prebuild，包括故障排查时。独立的 Expo 生产项目可以使用 CNG；请将其生成的 ios/ 和 android/ 与使用它们的应用分开存放。

Expo 支持两种将 React Native 添加到 Brownfield 项目的方式：

方式	发布到原生应用中的内容	适用场景
隔离式	预构建的 AAR / XCFramework	原生团队无需 Node 或 RN 工具；RN 代码可以存放在单独的仓库中
集成式	添加到现有 Gradle / CocoaPods 构建中的 React Native 源码	一个团队负责所有内容；熟悉 RN 工具；希望使用单一构建

完整的决策矩阵请参阅 ./references/comparison.md。

选择一种方式

使用以下快速规则；如有不明确之处，请参阅 comparison.md。

• 如果 iOS/Android 团队必须将 RN 作为常规库依赖项（AAR 或 XCFramework）使用，且不安装 Node、Yarn 或 React Native 构建工具链，请选择隔离式。
• 如果 RN 代码和原生代码位于不同的仓库，或按不同的节奏发布，请选择隔离式。
• 如果一个团队同时负责原生代码和 RN 代码，并愿意将 React Native + Expo 添加到原生项目的 Gradle 和 CocoaPods 配置中，请选择集成式。
• 两种方式都支持在 Debug 模式下使用 Metro 和 Fast Refresh。选择集成式是为了共享构建责任，而不是因为隔离式不支持实时 JS 迭代。

参考资料

• ./references/brownfield-isolated.md -- 将 RN 构建为 AAR/XCFramework，并在原生应用中使用（BrownfieldActivity、ReactNativeViewController、ReactNativeView）
• ./references/brownfield-integrated.md -- 将 RN 和 Expo 直接添加到现有的 Gradle 和 CocoaPods 构建中，同时保留原生应用外壳
• ./references/feature-integration.md -- 传递输入、返回结果、关闭、清理监听器并转发生命周期事件；包含 SwiftUI 宿主应用示例
• ./references/comparison.md -- 选择方式时的决策标准、权衡因素和场景映射
• ./references/troubleshooting.md -- 两种方式都可能遇到的 Metro 连接、构建、签名和模块解析问题

更多信息请访问 https://docs.expo.dev/brownfield/overview/

通用前置条件

以下两种方式都要求在_构建_ React Native 部分的环境中具备：

• Node.js（LTS） — 用于运行 Expo CLI 和 JavaScript 代码。
• 项目的包管理器和锁文件 — npm、Yarn、pnpm 或 Bun。请勿仅为遵循示例而更换包管理器。

iOS 构建环境需要 Xcode 和 CocoaPods（如果项目使用 Gemfile/Bundler 配置，请沿用）。隔离式方式的使用方应用需要 Xcode，但仅使用构建产物时不需要 CocoaPods 或 RN 工具。

选择兼容版本

对于现有的 Expo/RN 项目，请保留其选定的 SDK，并使用 npx expo install 对齐依赖项。不要仅仅为了遵循此技能而升级项目。对于新的生产者，请使用与宿主的 OS 支持、依赖项和构建工具链兼容的当前稳定版 SDK；选择前请确认该版本已稳定发布。

进行原生配置前，请阅读 ./references/version-compatibility.md，了解各 SDK 版本对应的原生模板、工具链/OS 要求和构建默认设置。纯原生客户端无需固定 Expo SDK 版本，但必须满足产物的要求。

在宿主中验证功能

打开 RN 屏幕并输入内容，将结果返回给原生端，关闭后再使用新输入重新打开。检查监听器清理情况，以及宿主原有的导航是否正常。然后使用 Release 版本的产物构建宿主，并停止 Metro。仅在 Expo Go 或生产者的示例应用中渲染，并不能验证集成。完整的验收场景请参阅 ./references/feature-integration.md。

提交反馈

如果你在此技能中遇到错误、误导性信息或过时信息，请报告，以便 Expo 改进：

npx --yes @expo/agent-cli@latest feedback --category skills --subject "expo-brownfield" "<actionable feedback>"

仅在有具体且可采取行动的问题时提交。请尽可能提供相关背景信息。 如果 Agent 在 Expo 任务中反复失败，或用户不得不介入，请使用 --category evals 提交简要报告，说明任务、预期结果和出错情况，并将相关 Expo 包或命令作为 --subject。