【全网最全】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 了不存在的代码）。

二

三

四