This documentation is available as Markdown for AI agents and LLMs. See the full Markdown index or append .md to any documentation URL.
Expo 棕地
用于将 Expo 集成到现有原生应用中的工具包和 API。
expo-brownfield 是一个用于向现有原生 Android 和 iOS 应用添加 React Native 视图的工具包。它提供:
- 内置 API 用于原生应用与 React Native 应用之间的双向通信和导航
- 配置插件 用于在你的 Expo 项目中自动设置棕地目标
- CLI 用于构建并发布到 Maven 仓库(Android)和 XCFrameworks(iOS)的工件
安装
🌐 Installation
If you are installing this in an existing React Native app, make sure to install expo in your project.
用法
🌐 Usage
通信 API
🌐 Communication API
通信 API 允许本地(宿主)应用与 React Native 之间进行双向、基于消息的通信。
🌐 The Communication API enables bi-directional, message-based communication between the native (host) app and React Native.
从 React Native 发送消息到原生
🌐 Sending messages from React Native to native
import * as Brownfield from 'expo-brownfield'; Brownfield.sendMessage({ type: 'MyMessage', data: { language: 'TypeScript', expo: true, platforms: ['android', 'ios'], }, });
在 React Native 中接收来自本地用户的消息
🌐 Receiving messages from native in React Native
import * as Brownfield, { type MessageEvent } from 'expo-brownfield'; import { useEffect } from 'react'; function MyComponent() { useEffect(() => { const handleMessage = (event: MessageEvent) => { console.log('Received message:', event); }; Brownfield.addMessageListener(handleMessage); return () => { Brownfield.removeMessageListener(handleMessage); }; }, []); // ... }
从原生发送消息到 React Native
🌐 Sending messages from native to React Native
import expo.modules.brownfield.BrownfieldMessaging BrownfieldMessaging.sendMessage(mapOf( "type" to "MyAndroidMessage", "timestamp" to System.currentTimeMillis(), "data" to mapOf( "platform" to "android" ) ))
import ExpoBrownfield BrownfieldMessaging.sendMessage([ "type": "MyIOSMessage", "timestamp": Date().timeIntervalSince1970, "data": [ "platform": "ios" ] ])
在原生中接收来自 React Native 的消息
🌐 Receiving messages from React Native in native
import expo.modules.brownfield.BrownfieldMessaging val listenerId = BrownfieldMessaging.addListener { event -> println("Message from React Native: $event") } // Later, to remove the listener: BrownfieldMessaging.removeListener(listenerId)
import ExpoBrownfield let listenerId = BrownfieldMessaging.addListener { message in print("Message from React Native: \(message)") } // Later, to remove the listener: BrownfieldMessaging.removeListener(id: listenerId)
应用配置中的配置
🌐 Configuration in app config
expo-brownfield 包提供了一个 配置插件,可用于在使用 连续原生生成 (CNG) 时配置棕地集成。这个插件允许你自定义 Expo 项目如何打包并集成到你现有的原生应用中。
🌐 The expo-brownfield package provides a config plugin that can be used to configure the brownfield integration when using Continuous Native Generation (CNG). This plugin allows you to customize how your Expo project is packaged and integrated into your existing native app.
Example app.json with config plugin
Configurable properties
发布工件
🌐 Publishing artifacts
expo-brownfield 命令行工具将 Android 工件推送到一个或多个 Maven 仓库,这些仓库通过你应用配置中的 android.publishing 声明。支持的仓库类型有:
🌐 The expo-brownfield CLI pushes Android artifacts to one or more Maven repositories, declared via android.publishing in your app config. The supported repository types are:
remotePrivate 上的 url、username 和 password 可以接受普通字符串或一个 EnvValue 对象({ "variable": "SOME_ENV_VAR" }),这个对象会通过 Gradle 的 providers.environmentVariable(...) 在构建时解析值。把秘密信息关联到环境变量,这样它们就不会出现在你提交的应用配置中。
发布到 GitHub 包
🌐 Publishing to GitHub Packages
GitHub Packages 托管了一个针对 GitHub 仓库的私有 Maven 仓库。认证使用 GITHUB_ACTOR(用户或机器人名称)和带有 write:packages 和 read:packages 权限范围的个人访问令牌 (PAT)。在 GitHub Actions 中,工作流的 GITHUB_TOKEN 已经拥有自己仓库所需的正确权限范围。
🌐 GitHub Packages hosts a private Maven repository scoped to a GitHub repo. Authentication uses GITHUB_ACTOR (the user or bot name) and a personal access token (PAT) with the write:packages and read:packages scopes. In GitHub Actions, the workflow's GITHUB_TOKEN already has the right scopes for the workflow's own repo.
在 android.publishing 中添加一个指向你的测试仓库 GitHub Packages URL 的 remotePrivate 条目:
🌐 Add a remotePrivate entry to android.publishing pointing at the GitHub Packages URL for your test repository:
name 字段同时控制 Gradle Maven 仓库名称和 --repo CLI 标志的值。使用 "name": "GitHubPackages" 后,发布任务变成了 publishBrownfieldReleasePublicationToGitHubPackagesRepository(调试版本则是 publishBrownfieldDebugPublicationToGitHubPackagesRepository)。默认调用会同时运行两者:
🌐 The name field controls both the Gradle Maven repo name and the --repo CLI flag value. With "name": "GitHubPackages", the release publish task becomes publishBrownfieldReleasePublicationToGitHubPackagesRepository (and publishBrownfieldDebugPublicationToGitHubPackagesRepository for the debug sibling). The default invocation runs both:
只发布融合后的工件
🌐 Publishing only the fused artifacts
非融合发布流程会为每个自动链接的 Expo Android 模块生成一个 Maven 坐标(每次发布通常有 20 到 40 个构件)。如果想发布一个小而精选的集合,可以使用 --fused。融合模式会跳过发布插件的每个模块的重发布循环,只生成胖 AAR 兄弟文件。始终需要一个仓库(--repo)或一个显式任务(-t),因为没有默认值:
🌐 The non-fused publish flow emits one Maven coordinate per autolinked Expo Android module (typically 20 to 40 artifacts per release). To publish a small, curated set instead, use --fused. The fused mode short-circuits the publish plugin's per-module re-publish loop and only emits the fat AAR sibling(s). A repository (--repo) or an explicit task (-t) is always required, as there is no default:
每次发布最多只有两个 Maven 坐标,不管你的项目自动链接了多少 Expo 模块。其他的东西(每个模块的 AAR、传递的 Maven 依赖)都不会进入你的远程仓库。基础库(AndroidX、RN 运行时、Kotlin 标准库、宿主已有的 Glide 替代库)在 POM 中保持外部引用,而不是融合进 AAR。
🌐 That's at most two Maven coordinates published per release, independent of how many Expo modules your project autolinks. Everything else (per-module AARs, transitive Maven deps) stays out of your remote repo. Foundational libraries (AndroidX, RN runtime, Kotlin stdlib, Glide alternatives the host already has) stay external in the POM rather than fusing into the AAR.
融合模式
🌐 Fused mode
--fused 通过两个额外的 Gradle 子项目发布,这些子项目总是由 prebuild 生成 —— :<libraryName>-fused-release 和 :<libraryName>-fused-debug —— 每个都通过 AGP 的 Fused Library 插件 输出一个胖 AAR(这是一个预览功能;CLI 在这些构建中会暂时强制使用 AGP 8.13)。在普通构建期间,这些子项目是静态的:它们的构建脚本只有在 CLI 传入 -Pbrownfield.fused=true 时才会激活,所以 npx expo run:android 和 IDE 同步不会额外增加配置成本。如果你直接调用 fused Gradle 任务而不是通过 CLI,需要自己传入 -Pbrownfield.fused=true。
并不是所有内容都被融合进 AAR。构建会将三种依赖保持为外部依赖,并在发布的 POM 和 Gradle 模块元数据中将它们声明为普通的 Maven 依赖,由宿主应用自行解析:
🌐 Not everything is fused into the AAR. The build keeps three kinds of dependencies external and declares them as ordinary Maven dependencies in the published POM and Gradle Module Metadata, where the host app resolves them itself:
- 棕地宿主基线 —— React Native 运行时(
react-android、hermes-android、fbjni、soloader、yoga)、Kotlin 标准库,以及宿主提供的通用库(Material Components、Guava、Fresco、OkHttp、Okio)。将它们合并会导致宿主已经提供的类被重复。 androidx.*库 — AGP Fused Library 的类重写器无法解析它们 styleables 中的android:框架属性,因此除了出于验证原因必须融合的链(默认是androidx.camera、androidx.media3)之外,所有 AndroidX 都保持外部。- 自动检测的 KMP 伞模块 — 只有 pom 的坐标,其所有变体都重定向到一个平台模块。
已发布的元数据还会使用兄弟模块的构建类型标注 react-android 和 hermes-android 依赖边,所以主应用总是会解析与融合 AAR 的原生库链接时相同的 React Native 版本,即使调试主应用使用的是发布版 AAR。
🌐 The published metadata also annotates the react-android and hermes-android dependency edges with the sibling's build type, so a host app always resolves the same React Native variant the fused AAR's native libraries were linked against, even when a debug host consumes the release AAR.
当项目的依赖图需要时,有五个 Gradle 属性可以调整这种行为:
🌐 Five Gradle properties tune this behavior when a project's dependency graph needs it:
在从 android 目录直接调用融合发布任务时,将它们作为 -P Gradle 属性传递:
🌐 Pass them as -P Gradle properties when invoking a fused publish task directly from the android directory:
注意:在进行融合之前,先检查你的宿主应用已经使用了哪些库。如果宿主自带 Glide(
expo-image融合了 Glide)、Jetpack Compose(@expo/ui)或类似库,融合后的 AAR 内的副本在构建时会与宿主的冲突(重复类),或者通过 POM 强制升级它。最好不要把这些 Expo 模块放进项目里,或者把共享的库标记为brownfield.fused.host-provided并手动对齐版本。
示例 GitHub Actions 工作流
🌐 Sample GitHub Actions workflow
通过 git tag brownfield-v1.0.0 && git push --tags 触发(或手动在 Actions 标签页触发)。工作流内置的 GITHUB_TOKEN 只适用于工作流自己的仓库,所以要发布到第三方仓库,需要在仓库密钥中使用 PAT。
🌐 Trigger via git tag brownfield-v1.0.0 && git push --tags (or manually via the Actions tab). The workflow's built-in GITHUB_TOKEN is scoped to the workflow's own repo, so publishing to a third-party repo requires a PAT in a repo secret instead.
消费者设置(主机安卓应用)
🌐 Consumer setup (host Android app)
宿主应用的 settings.gradle.kts(或每个模块的 build.gradle.kts)声明了相同的 GitHub Packages URL 和凭据。宿主应用的 CI/本地构建必须设置 GITHUB_ACTOR 和 GITHUB_TOKEN 环境变量,或者从 ~/.gradle/gradle.properties 中获取。
🌐 The host app's settings.gradle.kts (or per-module build.gradle.kts) declares the same GitHub Packages URL and credentials. The host app's CI/local builds must have the GITHUB_ACTOR and GITHUB_TOKEN env vars set or pulled from ~/.gradle/gradle.properties.
releaseImplementation/debugImplementation 会自动配对变体。Gradle 会根据宿主的构建类型选择匹配的同级版本。如果你的宿主只发布 release 构建,你可以去掉 debugImplementation 这一行,只用 --fused --release 发布 release 同级版本。
一些主机应用的要求和小贴士:
🌐 A few host app requirements and tips:
minSdk必须至少为 24(React Native 的下限)。当宿主使用 AAR 时,如果目标 API 级别低,会在清单合并时失败。- 权限会从融合的模块中合并而来。 例如,媒体相关的 Expo 模块会声明存储权限。如果你的宿主应用执行权限允许列表,可以用
tools:node="remove"在宿主清单中去掉不想要的条目(或者用tools:replace解决属性冲突)。 - AAR 在发布时会为每个启用的 ABI 提供本地库。 如果不进行过滤,主机 APK 的大小会增加相当于四个 ABI 的 React Native 库。发布时可以限制 ABI(在 Expo 项目的 gradle.properties 中设置
reactNativeArchitectures=arm64-v8a)或者在主机中用ndk.abiFilters/APK 分割进行过滤。
命令行接口
🌐 CLI
expo-brownfield 库包含一个用于构建和发布到 Maven 仓库(Android)以及 XCFrameworks(iOS)的命令行工具(CLI)。
🌐 The expo-brownfield library includes a CLI for building and publishing to Maven repositories (Android) and XCFrameworks (iOS).
命令
🌐 Commands
build:android
构建并发布棕地库及其依赖到 Maven 仓库。
🌐 Builds and publishes the brownfield library and its dependencies to Maven repositories.
build:ios
构建棕地 XCFramework 并将 Hermes XCFramework 复制到 artifacts 目录。
🌐 Builds the brownfield XCFramework and copies the Hermes XCFramework to the artifacts directory.
tasks:android
列出所有可用的发布任务和 Maven 仓库。
🌐 Lists all available publish tasks and Maven repositories.
应用接口
🌐 API
import * as Brownfield from 'expo-brownfield';
No API data file found, sorry!