在 Expo Monorepo 中做 Brownfield 集成測試brownfield-tester 應用的結構、產物構建與兩種消費模式【免費下載鏈接】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本篇技術指南以 Expo 官方倉庫中的 brownfield-tester 示例應用 為核心講解如何用一個完整可運行的示例驗證把 Expo 集成進既有原生 App即 brownfield 改造的工程路徑既包括產出可復用原生產物的 Expo 應用端也包括分別依賴源碼自動鏈接integrated與依賴預編譯產物isolated的兩類宿主原生工程。讀完本文你將掌握expo-brownfieldCLI 的產物構建命令、app.json中 config plugin 的關鍵參數以及兩種分發(fā)/消費模式各自的適用場景與工程前提。什么是 Brownfield Tester它在倉庫中扮演什么角色在 Expo 語境下brownfield 指的是已有的、非 Expo 創(chuàng)建的原生 Android/iOS 應用需要以增量方式接入 Expo 能力Expo Modules、expo-router、expo-updates 等而不是整體遷移到 Expo 托管工作流。Expo 為此提供了expo-brownfield工具包與相關 API。brownfield-tester 就是這個 monorepo 中專門用于驗證與回歸測試 brownfield 集成的示例工程集。它主要有兩個職責作為expo-brownfield包及其與expo-router、expo-updates、expo-dev-menu等包集成效果的測試載體作為expo-brownfieldE2E 測試的基礎應用base app供自動化測試反復構建與裝載。因此它不是一個玩具 Demo而是一套能真正跑通產物構建 → 宿主集成的最小可復現基線。三目錄總體結構一份 JS 源、兩種原生宿主倉庫根目錄為apps/brownfield-tester內部按職責劃分三個子工程目錄定位與 monorepo 的關系expo-appReact Native / Expo 應用既是JavaScript 源碼所在也是brownfield 產物的構建器直接以workspace:*依賴 monorepo 中的expo、expo-brownfield等包integrated原生 Android/iOS App通過 Expo autolinking 直接集成 monorepo構建時把 project root 指向../expo-app構建期從 monorepo 的node_modules解析并鏈接 React Native 模塊isolated獨立、自包含的原生 App消費預構建好的 brownfield 產物Android 走 Maven LocaliOS 走 xcframework/Swift Package構建期完全不依賴 monorepo是推薦的分發(fā)方式一句話概括expo-app負責把 Expo 應用打成可復用產物而integrated與isolated是消費這些產物的兩種宿主 App 形態(tài)。expo-appJavaScript 源與 brownfield 產物構建器依賴與運行腳本expo-app/package.json 顯示其運行腳本與常規(guī) Expo 應用一致expo start、expo run:android、expo run:ios依賴則全部指向 monorepo workspaceexpo、expo-brownfield、expo-router、expo-dev-menu、expo-updates見其README提到的測試目標、expo-image、expo-web-browser、expo-splash-screen、expo-status-bar、expo-constants等均為workspace:*底層 React Native 為 0.87.0、React 19.2.3并攜帶react-native-reanimated/react-native-worklets等典型 Expo 生態(tài)依賴。這意味著 expo-app 直接編譯并測試的是 monorepo 中尚未發(fā)版的expo-brownfield源碼是包開發(fā)期最直接的驗證環(huán)境。Metro 調試模式按 expo-app/README.md 的說明若要在 Debug 下配合 Metro Bundler 使用# 在 expo-app 目錄內 yarn start并且宿主 App 必須使用Debug或All構建類型的產物該限制當前僅 Android 支持。這是原生宿主在開發(fā)期加載 JS bundle 時最常見的坑產物構建類型與 Metro 啟動狀態(tài)不一致會導致加載不到 bundle。入口注冊除了主入口還有一個可獨立裝載的原生組件expo-app/index.js 展示了 brownfield 宿主應用場景下的入口寫法import { registerRootComponent } from expo; import { App } from expo-router/build/qualified-entry; import { AppRegistry } from react-native; import { CustomComponent } from ./src/components; // main component from expo-router registerRootComponent(App); // Additional custom component AppRegistry.registerComponent(custom-component, () CustomComponent);其中既注冊了以 expo-router 為主的主入口App又額外通過AppRegistry.registerComponent注冊了一個名為custom-component的獨立組件。這對應真實 brownfield 場景中宿主原生頁面想嵌入一塊 Expo 渲染的 UI的需求——原生端可以選擇把整個路由應用掛到全屏容器也可以把這塊自定義組件嵌入既有原生界面的任意位置。插件化配置與 UI 測試面expo-app/app.json 中配置了expo-router、expo-splash-screen以及最關鍵的自定義插件expo-brownfield{ plugins: [ expo-router, [expo-splash-screen, { backgroundColor: #208AEF, image: ./assets/images/splash-icon.png, imageWidth: 76 }], [ expo-brownfield, { ios: { buildReactNativeFromSource: false }, android: { publishing: [{ type: localMaven }] } } ] ] }從該配置可見兩個重要的產物策略開關iOS 側關閉了從源碼構建 React NativeAndroid 側指定產物以localMaven本地 Maven 倉庫方式發(fā)布。UI 結構則由 expo-app/src/app/_layout.tsx 中的Tabs路由承載包含Home與APIs兩個頁簽其中apis組下按測試目標拆分了 communication通信、dev-menu開發(fā)者菜單、native-modules原生模塊、navigation導航、state狀態(tài)等入口——從目錄設計可以推斷它們分別覆蓋 brownfield 場景下宿主與 Expo 側通信、開發(fā)菜單集成、自定義原生模塊橋接、導航與狀態(tài)同步等核心回歸面。構建可復用 brownfield 產物expo-brownfield 內置 CLIexpo-app/README.md 明確指出把 expo-app 打成可復用 brownfield 產物最直接的方式是使用expo-brownfield的內置 CLI# Android —— 構建并把產物發(fā)布到 Maven Local npx expo-brownfield build:android --repo MavenLocal --all --verbose # iOS —— 構建 xcframework 產物 npx expo-brownfield build:ios --release --verbose npx expo-brownfield build:ios --debug --verbose命令要點解讀--repo MavenLocal把 Android 的 brownfield 庫產物發(fā)布到本地 Maven 倉庫mavenLocal()供獨立宿主工程解析--all一次性構建全部所需的 build type可對應 Debug/Release 等變體--verbose輸出詳細日志便于在集成失敗時定位問題iOS 的--release/--debug是構建 flavor因為產物以 xcframework/Swift Package 形式輸出而 Swift Package Manager 不支持按構建配置重載.binaryTarget因此每個 flavor 需要單獨構建一次、分發(fā)兩個包詳見下文。消費模式一Integrated —— 基于 Expo autolinking 的直接集成integrated/README.md 說明integrated/下的原生工程直接與 Expo monorepo 集成其構建/project root 被指向../expo-app從而在構建期從 monorepo 的node_modules解析并鏈接 React Native 模塊。需要特別強調的是該 README 自帶一段醒目的 [!WARNING]這個應用把構建與 project root 重定向到了../expo-app這不是合法的工程配置需要重構。請不要把這種寫法復制到其他測試或 E2E 工程中。也就是說integrated/的存在意義是驗證 autolinking 鏈路本身能否工作它的工程結構屬于刻意為之的非法形態(tài)僅限倉庫內部測試使用。這提醒我們真實項目不應通過改 project root 的方式接 monorepo。Android 集成要點integrated從源碼結構看Android 端工程遵循官方 Brownfield Integration 指南的接入方式宿主工程位于 integrated/android通過 Android Studio 2025.1.3 的空 Activity 工程起步最終手工接入 Expo。關鍵的實施后置步驟包括由于 React Native 面向Java 17編譯需移除app/build.gradle.kts中默認的compileOptions需移除settings.gradle.kts中dependencyResolutionManagement的repositoriesMode因為react-native插件會自行配置 maven 倉庫二者疊加會沖突。工程中可以看到承載 Expo 渲染的原生活動類如ExpoActivity.kt以及入口MainActivity.kt、應用級MyApplication.kt即原生殼 Expo 承載視圖的典型布局。iOS 集成要點integratediOS 端工程位于 integrated/ios由 Xcode 26 的 SwiftUI 工程起步并同樣遵循官方指南接入。由于當前Swift 6 尚未被完全支持需要在工程設置里把 Default Actor isolation 設為nonisolated。源碼中包含ExpoView.swift、ExpoViewController.swift等承載層文件對應在 SwiftUI/UIKit 原生界面中嵌入 Expo 內容的接入方式。消費模式二Isolated —— 消費預構建產物推薦分發(fā)方式isolated/README.md 描述的isolated/是與 monorepo完全解耦的獨立原生 AppAndroid從Maven Local倉庫解析預發(fā)布的 brownfield 庫iOS通過Swift Package引入預構建的 xcframework構建期不使用 Expo autolinking也不依賴 monorepo 的node_modules。這是官方推薦的、面向既有原生 App 分發(fā) brownfield 集成能力的方式——宿主工程可以獨立于 Expo 倉庫構建、發(fā)布與演進。先決條件先生成產物構建 isolated 宿主前必須先進入expo-app生成產物isolated/README.md 給出的完整流程為cd ../expo-app # Android —— 先 prebuild 生成原生目標再構建并發(fā)布到 MavenLocal npx expo prebuild --clean -p android npx expo-brownfield build:android --repo MavenLocal --all --verbose # iOS —— 先 prebuild 生成原生目標再構建 xcframework npx expo prebuild --clean -p ios npx expo-brownfield build:ios --release --verbose npx expo-brownfield build:ios --debug --verbose這里npx expo prebuild --clean -p platform的作用是讓 config plugin包括expo-brownfield生效先生成出供產物構建使用的完整原生工程。產物細節(jié)可繼續(xù)參考 expo-app/README.md。Android直接打開、正常構建產物發(fā)布到 Maven Local 后用 Android Studio 打開 isolated/android 正常構建即可宿主 App 會從mavenLocal()解析 brownfield 庫。從源碼結構看Android 宿主包含MainActivity.kt、ReactNativeActivity.kt以及演示自定義原生模塊的BrownfieldTestModule.kt/BrownfieldTestPackage.kt覆蓋宿主 → 原生模塊 → React Native 側的往返調用。iOS通過本地 Swift Package 引入iOS 產物xcframeworks構建完成后可通過 E2E 腳本目錄中的add_xcframeworks.rb腳本把包含這些 framework 的 Swift Package 加入 Xcode 工程也可以在 Xcode 里通過Add Package Dependencies手動添加本地 package 路徑。從 expo-brownfield 包源碼看 CLI 與插件能力產物構建與宿主集成背后的實現來自 expo-brownfield它提供了一套完整的工具鏈倉庫內可見其cli/CLI 實現、android/、ios/、gradle-plugins/、plugin/config plugin、scripts/與e2e/等模塊結構上印證了配置插件 雙端產物構建 宿主集成腳本的分層設計。Config plugin 與核心選項在 app.json/app.config.js 中加入插件即可expo prebuild會根據插件為 brownfield 場景生成額外的原生 target{ plugins: [expo-brownfield] }需要自定義時可傳入選項例如指定 iOS target 名稱或 Android 庫名{ plugins: [ [ expo-brownfield, { ios: { targetName: MyBrownfield }, android: { library: mybrownfield } } ] ] }不加額外選項時均使用默認值。brownfield-tester 工程本身見 expo-app/app.json就是通過插件選項控制產物行為的真實范例。iOS 預編譯模塊與 SPM 共享依賴expo-brownfield的 iOS 產物構建支持配合expo-build-properties的ios.usePrecompiledModules讓pod install直接下載各 Expo 模塊的預編譯.xcframework而非源碼編譯隨后build:ios會自動識別ios/Pods/下的 xcframework把它們連同 brownfield framework、React、Hermes 與ReactNativeDependencies一起打包進輸出的 Swift Package。由于 Swift Package Manager 不支持對.binaryTarget(path:)做按構建配置的重載每個輸出包被固定為其構建時的 flavor--debug與--release需各構建一次隨后把兩個包并排分發(fā)。此外多個 Expo 模塊會鏈接共享的 SPM 依賴如expo-image→SDWebImage、libavif。為避免宿主運行時出現Library not loaded: rpath/...崩潰build:ios會依次在 Pod 內部、發(fā)布到 npm 包的prebuilds目錄、或共享的.spm-deps/緩存中查找依賴找不到時直接以可操作的錯誤信息終止構建而不是產出一個運行時必崩的 Swift Package。同一宿主內嵌多個 brownfield frameworkiOS當一個宿主 iOS App 需要同時共存多個 Expo brownfield framework 時可開啟ios.multipleFrameworks: true。每個 brownfield framework 會獲得唯一的 Swift module 名其注冊的所有 ObjC 類通過objc(...)加TargetName_前綴pod 依賴圖里的 ObjC 符號也在編譯期被統(tǒng)一重寫前綴從而避免兩個 framework 攜帶重疊 pod 時的鏈接期重復符號錯誤。該符號改寫由pod install階段的小型 Ruby shim 與隨包分發(fā)的 Node worker 完成并在依賴圖變化時通過校驗和跳過重復執(zhí)行。如何在倉庫中實際跑起來結合三份 README一個完整的本地驗證路徑如下開發(fā)/調試 JS 側進入 expo-app執(zhí)行yarn start啟動 Metro宿主 App 需選用Debug/All構建產物當前僅 Android 支持。生成產物在 expo-app 中執(zhí)行npx expo prebuild --clean -p android或-p ios隨后運行對應的npx expo-brownfield build:android --repo MavenLocal --all --verbose或build:ios --debug/--release。以 isolated 方式消費推薦分發(fā)路徑Android 直接打開 isolated/android 用 Android Studio 構建從mavenLocal()解析iOS 通過add_xcframeworks.rb腳本或 Xcode 的 Add Package Dependencies 添加本地 Swift Package。以 integrated 方式回歸 autolinking參考 integrated/ 雙端工程但須注意其 project root 重定向屬于倉庫內刻意保留的非法形態(tài)僅供內部鏈路驗證不應在真實工程中復制。兩種消費模式如何選型維度integratedautolinkingisolated預構建產物模塊來源構建期從 monoreponode_modules鏈接構建期從mavenLocal()/ 本地 Swift Package 解析依賴關系強依賴 monorepo 與源碼完全自包含獨立構建產物形態(tài)無獨立可分發(fā)產物Android Maven 庫、iOS xcframework/Swift Package用途回歸驗證 autolinking 鏈路倉庫內部面向既有原生 App 的推薦分發(fā)方式注意事項project root 指向外部工程是非法形態(tài)需按 flavordebug/release分別構建并分發(fā)小結brownfield-tester 用一套緊湊的工程組織把 brownfield 集成的兩端——Expo 產物構建端與原生宿主消費端——完整地呈現在同一 monorepo 中expo-app既是測試面也是構建器integrated/驗證最底層的 autolinking 可行性isolated/則給出業(yè)界真正推薦的預構建產物分發(fā)范式。若你要在自己的既有原生工程中接入 Expo建議對照isolated/的產物構建流程與宿主接入步驟并結合 expo-brownfield 中的插件選項與 iOS 多 framework、SPM 依賴約束等細節(jié)即可復現一條從 JS 源碼到宿主 App 的完整集成鏈路。【免費下載鏈接】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創(chuàng)作聲明：本文部分內容由AI輔助生成（AIGC），僅供參考