5 步把源码构建的 Android 库跑上模拟器：react-native-macos 从构建到排障的完整指南

5 步把源码构建的 Android 库跑上模拟器react-native-macos 从构建到排障的完整指南【免费下载链接】react-native-macos[deprecated in favor of https://microsoft.github.io/react-native-windows/] React Native for macOS is an experimental fork for writing desktop apps using Cocoa项目地址: https://gitcode.com/gh_mirrors/re/react-native-macos如果你要修改 react-native-macos 的 Android 侧代码或想确认自己维护的 fork 还能正常出包最可靠的验证方式是从源码编译ReactAndroid、发布到本地 Maven 仓库、再让一个新建工程引用这份产物最后在模拟器上把构建、发布、模拟器运行和日志排查的闭环走一遍。本文按你实际会碰到的问题顺序分 5 步讲完整条开发体验流程。如果还没拿到仓库git clone https://gitcode.com/gh_mirrors/re/react-native-macos做完本文你能独立复现 Android 源码构建环境并知道每一环失败时该去哪里找原因。1️⃣ 先把三个必须锁死版本的 SDK 组件装齐这一步解决机器上到底要装什么构建才可能成功。很多第一次构建失败根因都不在代码而在 SDK 组件版本没对齐。在终端执行android打开 SDK Manager对照下面这张表勾选组件版本它管什么为什么是这个版本Android SDKplatform23编译期用的平台 APIReactAndroid/build.gradle 里写死compileSdkVersion 23SDK Build Tools23.0.1aapt、dx 等构建工具链同文件里buildToolsVersion 23.0.1Android Support Repository17提供 Support Libraryinstrumentation 测试的AndroidJUnitRunner依赖它几个容易忽略的点装比 23 更高的 platform 不会报错但编译基线始终锚定 23低于 23 则直接构建失败defaultConfig里minSdkVersion 16意味着 API 16 以下的设备跑不了你构建出的应用targetSdkVersion是 22 而不是 23这是上游配置本身的选择不用改。配置完成后可以在 ReactAndroid/DevExperience.md 里对照官方流程确认组件清单它是本仓库内置的权威步骤文档。2️⃣ 一条命令完成构建与发布installArchives这一步解决如何把 ReactAndroid 源码变成一个别的工程能依赖的构件。在仓库根目录执行./gradlew :ReactAndroid:installArchives:ReactAndroid指向哪个模块由根目录 settings.gradle 决定include :ReactAndroid, :RNTester:android:app这条命令内部实际分两个阶段跑理解这两阶段才能看懂报错出在哪编译阶段。ReactAndroid/build.gradle 里有一串download*/prepare*任务先把 boost、double-conversion、folly、glog 和 JavaScriptCore 头文件拉到build/downloads拼装进third-party-ndk目录然后调用ndk-build产出libreactnativejni等 so再连同 Java 源码打成 AAR。如果你的机器上已有这些依赖源码可以设置环境变量REACT_NATIVE_DEPENDENCIES指向该目录跳过下载boost 体积较大单独支持REACT_NATIVE_BOOST_PATH。发布阶段。ReactAndroid/release.gradle 中定义了installArchives任务类型是Upload目标仓库是一个本地文件路径task installArchives(type: Upload) { configuration configurations.archives repositories.mavenDeployer { repository url: file://${projectDir}/../android configureReactNativePom pom } }也就是仓库根目录下的android/目录会被当成一个 Maven 仓库来写。发布坐标由 ReactAndroid/gradle.properties 决定属性值含义GROUPcom.facebook.react组织坐标POM_ARTIFACT_IDreact-native构件名VERSION_NAME1000.0.0-master版本号刻意远高于 npm 上的 0.xPOM_PACKAGINGaar打包格式验证方式命令跑完后到仓库根目录的android/下看应当出现com/facebook/react/react-native/1000.0.0-master/层级目录里面有 AAR、sources、javadoc 和.pom文件。还有一个前提必须提前满足android-jscJavaScriptCore 的 Android 绑定要事先装进本地 Maven 仓库文档里对此只有一句假定已安装。原因是编译阶段的prepareJSC任务会直接从compile配置里取出android-jsc的 AAR 解包 so 文件installArchives不会替你发布它——缺了它构建会在依赖解析时就挂掉。3. 新建工程并让它真的引用你的构建产物这一步解决发布完了新工程凭什么用你的本地 AAR 而不是 npm 上的旧版。创建工程react-native init ProjectNameinit生成的工程默认依赖 npm registry 上发布的 react-native。如果不做任何处理Gradle 解析com.facebook.react:react-native时拿到的是预编译的旧版 AAR你installArchives的产物就被完全绕过了。原文档给出的对策只有两条路选其一即可把新工程package.json中 react-native 的版本号提升到一个大于 0.9 的值当时的 npm 最新版确保版本约束下本地构件可被解析为 react-native 配置代理proxying让依赖解析整体走你自己的 registry 或本地目录。验证方式改完后重新构建观察 Gradle 是否下载/命中1000.0.0-master最直接的办法是看依赖树里com.facebook.react:react-native的实际版本。4. 一条命令上模拟器run-android 替你做了五件事这一步解决应用怎么跑起来以及它跑起来时 CLI 背后到底执行了什么。先打开一个 Android 模拟器。官方文档推荐 Genymotion理由是启动快、支持快照适合反复安装—启动的调试循环不过它对adb来说和普通 AVD 没有区别adb devices都能列出来用标准 AVD 同样走得通。然后进入工程目录执行cd ProjectName react-native run-androidrun-android命令注册在 local-cli/runAndroid/runAndroid.js 中从源码看它依次做了五件事工程体检checkAndroid检查android/gradlew是否存在不存在直接提示 Android project not foundPackager 检查isPackagerRunning(args.port)探测 8081 端口默认来自RCT_METRO_PORT || 8081没跑就用startServerInNewWindow另开窗口拉起 JS 服务构建安装切到工程android/目录执行./gradlew installDebugWindows 下是gradlew.bat依赖解析在此命中你发布的1000.0.0-master本地 AAR端口反代对每台已连接设备执行adb reverse tcp:8081 tcp:8081把设备内的 8081 映射回宿主机应用靠它从本机 Packager 拉 JS bundle拉起 Activityadb shell am start -n package/package.MainActivity。多设备或自定义工程时常用的参数同样定义在该文件底部参数用途什么时候用--deviceId id指定某台设备adb devices可查多设备/多模拟器并存--variant name指定构建变体工程有 flavor 划分--appFolder nameAndroid 源码目录名默认app目录结构非默认--appId/--appIdSuffix指定要启动的 applicationId多应用 ID 的 flavor--main-activity name指定启动 Activity默认MainActivity入口不是 MainActivity--no-packager不自动拉起 Packager服务已在别处运行--port nPackager 端口默认 8081端口被占用验证方式命令顺利跑完后模拟器上应能看到应用界面并渲染出 JS 内容而不是白屏或 Unable to load script 提示。5. 崩了就分层定位adb logcat 看日志这一步解决应用没起来第一步查什么。标准动作就一条命令adb logcat然后在输出里找 Java 异常。结合第 4 步的执行链失败通常落在三层之一症状和排查位置完全不同故障层典型症状去哪看依赖解析失败installDebug阶段 Gradle 直接报缺依赖构建期日志android/目录是否为空、android-jsc 是否已发布JS bundle 加载失败应用启动但白屏提示连不上 dev server宿主机 8081 是否可达、adb reverse是否生效Java/原生崩溃日志出现FATAL EXCEPTION、AndroidRuntimeadb logcat中的堆栈能看到崩溃的 Activity 或 Module两个提速技巧过滤关键字adb logcat | grep -i ReactNative\|FATAL想要干净现场先adb logcat -c清空缓冲区再复现崩溃避免被历史日志淹没。如果崩溃发生在 JNI 层日志里还会出现ReactNativeJS或 so 库相关条目那说明问题出在 native 实现而非 Java 侧。 不想手工验证仓库自带两套自动化测试手工流程验证的是开发体验而仓库同时提供了验证源码正确性的自动化手段可以互相补充本地单元测试scripts/run-android-local-unit-tests.sh内部就是buck fetchbuck test ReactAndroid/src/test/...集成/instrumentation 测试ContainerShip/scripts/run-android-ci-instrumentation-tests.js逐个类执行并自动重试规避用例抖动更省事的是 package.json 里的 npm scripts基于 Docker 一键跑npm run test-android-unit、npm run test-android-instrumentation、npm run test-android-e2e。测试套件跑通后样本应用的渲染效果可以参考仓库中集成测试的参考截图两套手段的分工很清楚buck/Docker 脚本盯构建与模块本身是否正确本文的手工流程盯一个新工程能不能顺利吃下你的改动。收尾速查环节—动作—验证环节关键动作验证方式环境执行android核对 SDK 23 / Build Tools 23.0.1 / Support Repository 17三个组件均显示已安装前置android-jsc 装入本地 Maven构建期不再报缺依赖构建发布./gradlew :ReactAndroid:installArchives根目录android/下出现 AAR 与 POM新工程react-native init 版本号或代理二选一Gradle 命中1000.0.0-master运行模拟器 react-native run-android应用加载 JS 并正常渲染排障adb logcat找 Java 异常按上表对号入座定位故障层最后提醒本文所有版本号SDK 23、1000.0.0-master与 CLI 行为均以本仓库代码为准。这是 react-native-macos 这个实验性 fork 继承自上游 React Native 的 Android 构建链路若你手上的 SDK 或 CLI 版本更新请以对应版本的构建日志为准。【免费下载链接】react-native-macos[deprecated in favor of https://microsoft.github.io/react-native-windows/] React Native for macOS is an experimental fork for writing desktop apps using Cocoa项目地址: https://gitcode.com/gh_mirrors/re/react-native-macos创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考