「原生 + RN 混合工程」一条命令启动全攻略：解密 react-native.config.js

Hybrid 开发模式越来越常见：原生 Android / iOS + React Native 模块混合开发。

但是，很多人遇到一个小坑：

我想直接在 Hybrid 工程里执行 yarn android，像纯 RN 工程一样一键跑起来，结果报错！

为什么会这样？React Native CLI 默认只认 ./android、./ios，根本不知道你的原生主工程在哪。

今天，我们就来揭秘 react-native.config.js，教你轻松解决这个问题，让 Hybrid 工程也能一条命令启动。

---

一、Hybrid 工程典型结构

先来看一个常见目录：

/HybridApp
   ├── /appA                # 原生 Android 工程（主工程）
   │     └── build.gradle
   │
   ├── /rnmodule            # React Native 模块
   │     ├── android/       # RN 的 Android library
   │     └── index.js
   │
   ├── package.json
   └── react-native.config.js

如果直接 yarn android，CLI 会去找 ./android， 但我们的 真正入口在 appA ------ 所以它当然会失败。

---

二、解决方案：配置 react-native.config.js

在根目录加一个配置文件：

// react-native.config.js
module.exports = {
  project: {
    android: {
      sourceDir: './appA',   // 指定原生主工程路径
    },
  },
  assets: [
    // 如果有字体、图片需要自动拷贝，可以在这里配置
    // 'rnmodule/assets/fonts',
  ],
};

这样，执行 yarn android 时，CLI 会自动进入 ./appA，执行：

cd appA && ./gradlew installDebug

APK 就能顺利安装并启动了 🚀

同时，Debug 模式下 JSBundle 会走 Metro，方便热更新调试。

---

三、react-native.config.js 的历史演进

• RN 0.59 及以前 没有 react-native.config.js，CLI 默认死板地只认 ./android、./ios。 要改路径只能硬改 CLI 源码。

• RN 0.60 引入 react-native.config.js 正式登场，替代早期的 rnpm。 支持配置：dependencies、assets、project.android.sourceDir、project.ios.sourceDir。

• RN 0.62+ react-native link、run-android、run-ios 全部基于这个配置。

• RN 0.70+ CLI 拆分成 @react-native/cli，但 react-native.config.js 依然是推荐方式。

👉 也就是说，从 RN 0.60 起就能用了，一直到今天都稳定可用。

---

四、CLI 内部调用链

那 CLI 到底是怎么用这个配置的呢？ 以 yarn android 为例，调用链大致是这样：

yarn android
   ↓
react-native/cli.js
   ↓
@react-native/cli (或 @react-native-community/cli)
   ↓
loadConfig(projectRoot)
   └── 读取 react-native.config.js
   ↓
run-android/index.js
   └── const sourceDir = config.project.android.sourceDir || 'android'
   ↓
cd ${sourceDir} && ./gradlew installDebug

一句话总结：

👉 CLI 每次执行命令时，都会去读取 react-native.config.js， 然后用里面的 sourceDir 来决定去哪执行 gradlew。

---

五、最终效果

配置好后，Hybrid 工程就能像纯 RN 工程一样用了：

yarn start    # 启动 Metro
yarn android  # 编译 appA 原生工程并安装到手机

再也不用手动 cd appA && ./gradlew installDebug 了，舒服～

---

🎯 总结

• Hybrid 工程默认 yarn android 会失败，因为 CLI 不知道主工程在哪。
• 在 react-native.config.js 里配置 project.android.sourceDir，就能解决。
• 这个机制从 RN 0.60 起支持，到现在依然是官方推荐做法。
• CLI 调用链：命令行 → 读取配置 → 确定工程目录 → 调用 gradlew。

小结一句话：配置 react-native.config.js，让 Hybrid 工程也能"一条命令启动"，从此告别手动切换目录和命令的烦恼。