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