企业官网建设流程全解析

Ignite 原生 Android 工程指南：manual 工作流下的 android 目录与 CNG 取舍

【免费下载链接】igniteInfinite Red's battle-tested React Native project boilerplate, along with a CLI, component/model generators, and more! 9 years of continuous development and counting.项目地址: https://gitcode.com/GitHub_Trending/ig/ignite

导读

本文围绕 Ignite 官方文档 docs/boilerplate/android.md 展开，系统讲解在创建新应用时选择manual工作流（或执行pnpm prebuild:clean）后，项目根目录出现的android原生工程的结构、生成方式、与 Expo CNG（Continuous Native Generation）工作流的取舍，以及如何用 Android Studio 调试、用 EAS 构建 Android 应用。读完本文，你将掌握 Ignite 项目中 Android 原生层的来源、改法与运行调试的全流程。

android 目录从哪里来：manual 工作流与 prebuild

在 Ignite 中，创建新应用时可以选择如何管理原生代码。CLI 会在交互过程中弹出如下选择（见 src/commands/new.ts）：

• Via Expo's Continuous Native Generation - Recommended [Default]（即cng，默认选项）
• Manual - commits android/ios directories（即manual）

cng是默认工作流：原生目录不提交到版本库，由 Expo Prebuild 在构建时按需生成。而选择manual时，android（以及对应的ios）目录会被创建并保留在项目根目录，作为可直接提交、可直接用 IDE 打开的"真·原生工程"。从源码看，manual 工作流还会从.gitignore中移除android和ios两行，使原生目录纳入版本控制（见 src/commands/new.ts）。

即使最初选择了cng，在项目根目录执行以下命令也会重新生成并保留原生目录：

pnpm prebuild:clean

该命令在 boilerplate/package.json 中定义为npx expo prebuild --clean。--clean会删除并重建原生工程，确保原生目录与当前的app.json/app.config.ts配置严格一致。

这个 android 目录是什么

android目录是一个已针对 React Native 预先配置好的 Android Studio 工程。它并非空壳，而是由 Expo Prebuild 依据项目配置自动生成的原生 Gradle 工程，包含app、gradle、build.gradle、settings.gradle等标准结构，可直接被 Android Studio 打开，在模拟器或真机上运行。

生成它的配置来源有两个文件：

• 静态配置 boilerplate/app.json：其中的android字段定义了应用标识与图标资源，例如package（包名com.helloworld）、icon（./assets/images/app-icon-android-legacy.png）、adaptiveIcon（前台/背景自适应图标）、allowBackup: false、edgeToEdgeEnabled: true等；顶层还声明了newArchEnabled: true（新架构）与jsEngine: "hermes"（Hermes 引擎），这些都会直接影响生成的 Gradle 配置。
• 动态配置 boilerplate/app.config.ts：通过module.exports动态合并ios与plugins等字段，是 TypeScript 形式的扩展配置入口。

也就是说，对android目录的手工改动，本质上是在"生成结果"上打补丁。这正是下一节要讨论取舍的原因。

官方推荐：优先使用 Expo CNG

原文档明确给出建议：一般情况下推荐使用 Expo CNG（Continuous Native Generation）工作流，详见 docs/expo/CNG.md。CNG 与手动管理原生目录相比，核心优势有三点：

1. 无需直接与 Gradle 和 CocoaPods 打交道：原生构建脚本由 Expo Prebuild 自动维护；
2. 升级成本显著降低：由于没有手改的原生代码"挡路"，React Native / Expo 升级时不会因原生层冲突而阻塞；
3. 生态支持完善：大量流行库都有现成的 config plugin，必要时也可以自行编写 config plugin 来自动生成原生配置。

而manual工作流的适用场景是：你确实需要手工修改原生代码。此时保留android目录直接编辑即可。

用 Android Studio 运行与调试原生代码

无论目录来自 manual 工作流还是prebuild:clean，它的用法与其他 React Native 项目完全一致：

1. 用 Android Studio 打开项目根目录下的android文件夹；
2. 等待 Gradle 同步完成；
3. 选择一个模拟器（AVD）或连接真机，点击 Run 运行应用；
4. 调试原生代码时可参考 React Native 官方文档中"Debugging native code"一节，在 Android Studio 中为 Java/Kotlin 代码设置断点、附加调试器。

除此之外，Ignite 在 boilerplate/package.json 中为 Android 日常开发准备了一组脚本：

# 在设备上安装并启动开发版应用（等效 expo run:android） pnpm android # 将 Metro、Reactotron 等端口反向转发到真机，便于真机调试 pnpm adb

adb脚本实际执行的是adb reverse tcp:9090 tcp:9090 && adb reverse tcp:3000 tcp:3000 && adb reverse tcp:9001 tcp:9001 && adb reverse tcp:8081 tcp:8081，覆盖了 Reactotron（9090）、常用本地服务（3000/9001）与 Metro（8081），是真机调试的常用前置步骤。

用 EAS 构建 Android 应用

当原生目录就绪后，还可以借助 Expo Application Services（EAS）在本地或云端构建 Android 安装包。Ignite 在 boilerplate/eas.json 中预置了多种构建 profile，并配套了对应的 npm 脚本：

以本地构建开发版为例：

pnpm build:android:sim # 等价于 eas build --profile development --platform android --local

对于原生层存在手工定制的项目，这种构建流程与manual工作流天然契合——因为构建所需的正是在android目录中手工调整过的工程。

小结

android目录是 Ignite 项目在 manual 工作流（或prebuild:clean）下生成的原生 Android Studio 工程，预配置齐全、可直接运行与调试。日常开发中，Ignite 更推荐 CNG 工作流以避免直接维护 Gradle；只有需要手工定制原生代码时才保留该目录。若需继续深入，可阅读 docs/boilerplate/ios.md（iOS 侧对应工程）、docs/expo/CNG.md（CNG 工作流详解），或在 boilerplate/app.json 与 boilerplate/app.config.ts 中查看驱动原生生成的完整配置。

【免费下载链接】igniteInfinite Red's battle-tested React Native project boilerplate, along with a CLI, component/model generators, and more! 9 years of continuous development and counting.项目地址: https://gitcode.com/GitHub_Trending/ig/ignite