【全网最全】React Native 安卓原生工程结构与构建机制深度解析

  1. 项目初始化:npm install 与 run-android 的爱恨纠葛
  2. 核心文件拆解:到底谁才是"施工图纸"?
  3. 目录角色:系统级缓存 vs 项目级缓存
  4. 应用配置:如何改名、换图标、切包名?
  5. 账号接入:第三方 SDK(推送/支付)Key 存放处
  6. 编译冷知识:找不到的代码与消失的任务
  7. 避坑指南:原生编译失败的通用自救流程

<a name="section-1"></a>

1. 项目初始化:npm install 与 run-android 的爱恨纠葛

  • 执行顺序 :必须先 npm install 再跑 npm run android。
  • 深层原因 :npm install 下载的是原生插件的 JS 桥接依赖,没有它,Gradle 无法找到对应的 Native 代码,会导致 Autolinking 失败。
  • npm vs npx :
    • npm run android:运行 package.json 中的脚本别名,建议团队内统一使用。
    • npx react-native run-android:直接运行 node_modules 里的二进制命令。

<a name="section-2"></a>

2. 核心文件拆解:谁才是"施工图纸"?

  • build.gradle (根目录) :全场总控脚本。 定义 SDK 版本、仓库地址(Google/Maven)及全局插件工具。
  • build.gradle :模块施工蓝图。 定义包名 (applicationId)、版本号、以及编译具体的厂商占位符。
  • gradle.properties :环境配置。 调节 JVM 内存空间、开启 AndroidX 支持。
  • gradlew (Gradle Wrapper) :内置管家。 确保每个开发者使用的 Gradle 核心版本完全一致,无需手动安装 Gradle。

<a name="section-3"></a>

3. 目录角色:系统级缓存 vs 项目级缓存

  • 系统盘缓存 (~/.gradle) :中央公共库。 存放全球下载的 .jar / .aar 依赖包,多项目共享。
  • 项目内临时目录 (android/.gradle) :编译草稿箱。 存放本次构建的中间缓存,通常为灰色(已在 .gitignore 忽略)。
  • android/app/ :原生宿主。 存放 MainActivity、图标资源、App 身份证 (AndroidManifest.xml)。

<a name="section-4"></a>

4. 应用配置:如何改名、换图标、切包名?

  • App 显示名称 :修改 strings.xml 中的 app_name。
  • 包名 (Bundle ID) :修改 build.gradle 中的 applicationId,它是 App 在应用商店的唯一身份标识。
  • App 图标 :存放于 res/mipmap 文件夹下,根据不同分辨率对应不同尺寸。

<a name="section-5"></a>

5. 账号接入:第三方 SDK Key 存放处

  • AndroidManifest.xml (meta-data) :
    • 用于存放阿里云推送、华为 AppID、小米/OPPO/Vivo 等 Key。这些 Key 由各大厂开发者平台分配。
  • queries 标签 :
    • iOS 风格的白名单:在 Android 11+ 中,必须在此声明你想跳转的应用(如微信、支付宝),否则 App 无法检测到它们。
  • build.gradle (manifestPlaceholders) :
    • 有些 Key 会通过变量注入的方式在编译时动态填入清单文件。

<a name="section-6"></a>

6. 编译冷知识:找不到的代码与消失的任务

  • 消失的 index.android.bundle :
    • Debug 模式下代码存放在 Metro 服务的内存中;仅在 Release 模式打包时才会生成物理文件并存放在 assets 目录下。
  • 冒号 : 的奥秘 :
    • 如 :app:compileDebugKotlin,冒号代表逻辑层级(主模块 app 下的编译任务),区别于文件系统的物理路径 /。
  • Kotlin 在 RN 中的角色 :
    • 它是 Google 官方语言,RN 项目(0.68+)默认使用 Kotlin 编写原生桥接层,与 JS/TS 代码共同协作。

<a name="section-7"></a>

7. 避坑指南:原生编译失败的通用自救流程

如果你遇到编译报错,请按以下"三板斧"操作:

  1. 清理现场 :执行 ./gradlew clean 删掉所有缓存。
  2. 兼容性转换 :执行 npx jetifier 确保老旧库适配 AndroidX 架构。
  3. 精准定位 :查看控制台中 e: 开头的错误行,寻找 Unresolved reference(通常说明你手动 import 了不存在的代码)。

二

三

四

相关推荐
Wellijohn5 小时前
一个 Android 老兵的十年开源路:从 167 star 的滑动控件,到本地优先的 AI Agent
android·人工智能·开源
好的佩奇10 小时前
Dart 之元数据与注解
android·flutter·dart
三少爷的鞋11 小时前
很多开发者把物理上的分层,当成了架构
android
FungLeo12 小时前
FengCMS · PHP+MySQL 升级实录 · MySQL DDL不能回滚:模型字段结构操作的失败续做
android·mysql·php·工程实践·fengcms
雨白13 小时前
Android 建造者模式实战:从 AlertDialog 源码到 TopBar 的两种实现
android
_祝你今天愉快15 小时前
Android 高级绘制:[五] 贝塞尔曲线与计算规则
android
FungLeo1 天前
FengCMS · PHP+MySQL 升级实录 · 危险默认值之殇:root/123456、认证码 8888 写进配置加载器
android·mysql·php·安全加固·fengcms
yz_aiks1 天前
Termux 使用教程:把安卓手机变成随身 Linux(装 Python、SSH 远程、跑自动化脚本)
android·linux·python·智能手机·ssh·termux
booboosui2 天前
编号没变,消息还是来了:Mac 端通知读取漏第二条的原因
android
壹楽2 天前
用 React 19.2 的 <Activity> 做多页签保活,我踩了 6 个坑
react.js