react-navtive实战记录

. . . . .2026-06-07 7:09

Taro + React Native Android/iOS 开发流程(实战版)

本文档基于本项目(demo)实际跑通过的流程整理。按顺序做,不需要其他参考。

适用场景

已有 Taro 4.x + React 18 项目,需要补全 Android/iOS 原生工程,跑通端到端(Gradle 编译 → Metro 启动 → 模拟器/真机看到 Taro 页面)。

0. 前置准备

确认本机环境:

工具 版本要求 验证命令
Node.js ≥ 18 node --version
pnpm ≥ 8 pnpm --version
JDK 17(Android Gradle Plugin 8.x 要求) java -version
Android Studio Hedgehog 或更新 App Store 装
Xcode(仅 iOS) 15+ App Store 装
CocoaPods(仅 iOS) ≥ 1.10 pod --version

1. 装 CocoaPods(仅 macOS,iOS 端必需)

bash 复制代码 
brew install cocoapods
pod --version # 应输出 1.10+

完整 Xcode 必须从 App Store 装,装完后切换命令行路径,否则 pod install 会报:

复制代码 
xcode-select: error: tool 'xcodebuild' requires Xcode,
but active developer directory '/Library/Developer/CommandLineTools' is a command line tools instance

切换命令:

bash 复制代码 
sudo xcode-select -s /Applications/Xcode.app/Contents/Developer
xcode-select -p  # 应输出 /Applications/Xcode.app/Contents/Developer

1.1 CocoaPods 源说明(国内)

本项目 ios/Podfile 使用 官方 CDN （cdn.cocoapods.org），并默认关闭 Flipper 以加速安装。

注意 ：mirrors.aliyun.com/cocoapods/Specs.git 已下线（404），不能像 Android 那样配 Gradle 阿里云 Maven 镜像。CocoaPods 与 Maven 是两套生态。

不要 再执行 pod repo add master https://mirrors.aliyun.com/...（会报 repository not found）。

现代 CocoaPods（≥1.8）用 CDN 即可，一般不必 克隆整份 master Specs 仓库。若 CDN 慢，可选用清华 git 源（体积大、首次 clone 久）:

ruby 复制代码 
# Podfile 顶部二选一（需改 Podfile 后重新 pod install）
source 'https://cdn.cocoapods.org/'
# source 'https://mirrors.tuna.tsinghua.edu.cn/git/CocoaPods/Specs.git'

2. 配置 Gradle 阿里云镜像(国内必需)

⚠️ 跳过这步在国内会失败 。Gradle 默认从 repo.maven.apache.org 拉依赖,这个域名被墙,会报:

复制代码 
repo.maven.apache.org: nodename nor servname provided, or not known
bash 复制代码 
mkdir -p ~/.gradle/init.d
cat > ~/.gradle/init.d/aliyun-mirror.gradle << 'EOF'
allprojects {
    buildscript {
        repositories {
            maven { url 'https://maven.aliyun.com/repository/public' }
            maven { url 'https://maven.aliyun.com/repository/google' }
            maven { url 'https://maven.aliyun.com/repository/gradle-plugin' }
            maven { url 'https://maven.aliyun.com/repository/central' }
        }
    }
    repositories {
        maven { url 'https://maven.aliyun.com/repository/public' }
        maven { url 'https://maven.aliyun.com/repository/google' }
        maven { url 'https://maven.aliyun.com/repository/gradle-plugin' }
        maven { url 'https://maven.aliyun.com/repository/central' }
    }
}

settingsEvaluated { settings ->
    settings.pluginManagement {
        repositories {
            maven { url 'https://maven.aliyun.com/repository/gradle-plugin' }
            maven { url 'https://maven.aliyun.com/repository/public' }
            maven { url 'https://maven.aliyun.com/repository/google' }
        }
    }
}
EOF

只配一次,以后任何 gradle 项目都自动走阿里云。

3. 初始化裸 RN 0.73.11 工程

bash 复制代码 
cd /Users/username/Documents

npx @react-native-community/cli@13.6.9 init TaroShell \
      --version 0.73.11 \
      --pm npm \
      --skip-install \
      --directory taro-shell-tmp

固定用 cli@13.6.9(配 RN 0.73.11)。不要用 latest(那是 20.x,配 RN 0.85+)。

预期 :RN 0.73.11 模板下载并展开,生成 taro-shell-tmp/ 目录(包含 android/、ios/、App.tsx、metro.config.js 等)。

4. 迁移 android/ ios/ 到 Taro 项目

bash 复制代码 
mv taro-shell-tmp/android taro-shell-tmp/ios /Users/username/Documents/demo/

rm -rf taro-shell-tmp

5. 验证 Android SDK 路径

Android Studio 第一次打开工程会自动写 local.properties,一般不用动。验证一下文件存在:

bash 复制代码 
cat /Users/username/Documents/demo/android/local.properties

预期 :文件存在,包含一行 sdk.dir=/Users/<你的用户名>/Library/Android/sdk。

(注释行内容随 Android Studio 版本不同,不用管。)

如果没有 sdk.dir 这一行,手动加:

bash 复制代码 
echo "sdk.dir=/Users/$(whoami)/Library/Android/sdk" >> /Users/username/Documents/demo/android/local.properties

6. 装 npm 依赖

Taro 模板不会自动装上以下依赖,必须手动补齐,缺一个 Metro 打包或 Gradle 编译就会报错。

bash 复制代码 
cd /Users/username/Documents/demo

# 6a. RN 工程依赖的 3 个 devDeps(分别给 Metro / Gradle 用)
#     @react-native/babel-preset: Metro 打包时用,处理 JSX 编译
#     @react-native-community/cli-platform-android: Gradle 编译时用,自动链接 native module
#     @react-native/gradle-plugin: Gradle 编译时用,让 Gradle 识别 RN 工程结构
pnpm add -D @react-native/babel-preset@0.73.21 \
            @react-native-community/cli-platform-android@13.6.9 \
            @react-native/gradle-plugin@0.73.5

# 6b. Taro RN 端必备的 3 个原生库
#     Taro 用 react-navigation 做路由栈,以下三个是它的 peer 依赖
pnpm add react-native-gesture-handler@~2.14.0 \
         react-native-safe-area-context@~4.7.0 \
         react-native-screens@~3.27.0

# 6c. 降级 stylelint 到 16.10.0
#     stylelint-taro-rn@4.2.0 期望 stylelint 在 16.4 ~ 16.10 之间
#     16.10 之后移除了 declarationValueIndex.cjs,Metro 编译 src/app.scss 时会报错
pnpm add -D stylelint@16.10.0

7. 改 MainActivity.kt 让组件名跟 Taro 一致

Taro 在 JS 侧用 config/index.ts 的 rn.appName: 'taroDemo' 注册根组件(不读 app.json)。

但 RN 模板生成的 MainActivity.kt 默认从 app.json 的 name 读,即 TaroShell,导致 app 启动时报:

复制代码 
ERROR  Invariant Violation: "TaroShell" has not been registered.

修复 :把 MainActivity.getMainComponentName() 改成 taroDemo,跟 Taro 注册的一致即可。不要改 app.json ,Taro 不读它的 name。

kotlin 复制代码 
// android/app/src/main/java/com/taroshell/MainActivity.kt
class MainActivity : ReactActivity() {
  // 改成跟 config/index.ts 的 rn.appName 一致
  override fun getMainComponentName(): String = "taroDemo"

  override fun createReactActivityDelegate(): ReactActivityDelegate =
      DefaultReactActivityDelegate(this, mainComponentName, fabricEnabled)
}

8. 验证 Android Gradle 配置

目的:在「真编译 APK」之前,用最便宜的方式确认工程配置是对的。

./gradlew tasks 做的事是让 Gradle 解析所有 build.gradle 脚本、加载依赖、列出可执行 task,不会真的编译任何 APK 。如果配置有问题(比如 cli-platform-android 没装、镜像没配、SDK 路径错),会在这里快速爆出来,而不是等到 installDebug 编了 5-10 分钟才报错。

不需要设备,只跑:

bash 复制代码 
cd /Users/username/Documents/demo/android
./gradlew tasks --no-daemon

gradlew 工作机制

./gradlew 是项目自带的 Gradle Wrapper,由两样东西组成:

复制代码 
android/
├── gradlew                ← shell 脚本(你敲命令的入口,macOS/Linux 用)
├── gradlew.bat            ← Windows 版
└── gradle/
    └── wrapper/
        ├── gradle-wrapper.jar          ← Java 包,真正干活的(下载/启动 Gradle)
        └── gradle-wrapper.properties   ← 配置文件,写死要下哪个 Gradle 版本

首次跑 ./gradlew 时:shell 脚本会调用 gradle-wrapper.jar,jar 按 gradle-wrapper.properties 里的 distributionUrl 下载对应版本的 Gradle,后续复用。这样不管本机装没装 Gradle、装的什么版本,所有人都用同一份。

./gradlew tasks 会按顺序读取以下配置(任一写错都会在这里爆):

  1. gradle/wrapper/gradle-wrapper.properties --- 决定用哪个 Gradle 版本
  2. ~/.gradle/init.d/*.gradle --- 全局 init 脚本(我们的阿里云镜像就在这)
  3. android/settings.gradle --- 工程结构、依赖仓库地址
  4. android/build.gradle --- 全局 SDK 版本、repositories
  5. android/app/build.gradle --- app 子项目配置(plugins、applicationId、依赖)
  6. android/gradle.properties --- JVM 参数

拆成两阶段理解

复制代码 
./gradlew <子命令>
   │
   ├─ 阶段 1:加载配置(固定,跟子命令无关)
   │     ↓
   │   1. gradle-wrapper.properties     ← 决定 Gradle 版本
   │   2. ~/.gradle/init.d/*.gradle     ← 全局 init(阿里云镜像)
   │   3. android/settings.gradle       ← 工程结构、模块、仓库
   │   4. android/build.gradle          ← 全局 SDK 版本
   │   5. android/app/build.gradle      ← app 配置
   │   6. android/gradle.properties     ← JVM 参数
   │
   └─ 阶段 2:执行子命令(看后面跟的是什么)
         ↓
       ├─ ./gradlew tasks            → 列出所有 task
       ├─ ./gradlew assembleDebug    → 编译 debug APK
       ├─ ./gradlew installDebug     → 编译 + 装到设备
       └─ ./gradlew build            → 编译所有产物

tasks 不特殊 。它跟 assembleDebug、installDebug 一样,先走一遍阶段 1(配置加载),然后阶段 2 执行「列 task」这个动作。

为什么要「tasks 跑通 ≈ installDebug 跑通」

因为阶段 1 完全相同:

  • tasks 阶段 1 失败 → 配置文件写错,installDebug 阶段 1 也会失败
  • tasks 阶段 1 通过 → 阶段 2 不管跑什么子命令都不会卡在配置

唯一的区别是 installDebug 阶段 2 会真的去编译 Java/Kotlin/资源,会涉及 NDK、AGP 内部配置等更深层的东西,但这部分只要阶段 1 OK,几乎不会再出错。

所以 tasks 命令的价值:用最低成本(只加载配置、列 task)验证配置正确性 ,比直接 installDebug 编 5-10 分钟发现配错划算得多。

bash 复制代码 
cd /Users/username/Documents/demo/android
./gradlew tasks --no-daemon

预期:

  • 第一次跑会下载 AGP、build-tools、NDK 等(从阿里云,1-10 分钟)
  • 列出 assembleDebug、installDebug 等 task
  • 最后 BUILD SUCCESSFUL

如果失败 ,把 * What went wrong: 那段贴出来分析。两个最常见错误:

错误 原因 修复
Could not read script .../native_modules.gradle @react-native-community/cli-platform-android 没装上 补第 6a 步
Could not GET ... repo.maven.apache.org: nodename nor servname 阿里云镜像没配 补第 2 步

9. 启动 Metro

bash 复制代码 
cd /Users/username/Documents/demo
npm run dev:rn

预期:

复制代码 
👽 Taro v4.2.0
✔ 获取 taro 全局配置成功
info Welcome to React Native v0.73
info Starting dev server on port 8081...
              Welcome to Metro v0.80.12

info Dev server ready
i - run on iOS
a - run on Android
d - open Dev Menu
r - reload app

Metro 必须保持运行,不要关。

10. 在 Android 模拟器/真机上跑

10a. 准备模拟器

打开 Android Studio,右上角 Device Manager → 创建/启动 Pixel 6 API 33。

或命令行启动:

bash 复制代码 
emulator -list-avds           # 列出可用 AVD
emulator -avd <name> &        # 启动
adb devices                    # 验证:emulator-5554 device

10b. 装 app 到设备

方式 A:Android Studio Run

  1. 顶部 "Add Configuration" → Edit Configurations → Module 选 app → OK
  2. 点 ▶ Run

方式 B:命令行(推荐,出错时更容易看日志)

bash 复制代码 
cd /Users/username/Documents/demo/android
./gradlew installDebug

首次跑 :5-10 分钟(下载 NDK、AGP、build-tools)。后续跑:增量编译,几秒到 1 分钟。

10c. 启动 app

installDebug 完成后,模拟器桌面向上滑 找 taroDemo 图标点开。

或命令行启动:

bash 复制代码 
adb shell am start -n com.taroshell/.MainActivity

预期:屏幕先红屏几秒(Metro 编译 bundle)→ 显示 Taro 默认页面。

11. 验证完整跑通

跑通后应该是这样:

终端 状态
Metro 终端 info Writing bundle output to: dist/rn/index.bundle + info Done writing bundle
Logcat LOG Running "taroDemo" with {"rootTag":...}(注意是 taroDemo 不是 TaroShell)
模拟器 显示 Taro 默认页面(有标题 + 按钮)

改 src/pages/index/index.tsx → 保存 → Metro 自动热更新 → 模拟器立即看到变化,无需 reload。

12. iOS 端(需要 Xcode)

当前是 Android 端跑通后的可选步骤。

bash 复制代码 
# 12a. 切换 Xcode 路径
sudo xcode-select -s /Applications/Xcode.app/Contents/Developer
xcode-select -p  # 应输出 /Applications/Xcode.app/Contents/Developer

# 12b. 装 iOS pods（Podfile 已配 CDN 源 + 关闭 Flipper）
cd /Users/username/Documents/demo/ios
pod install
# 需要 Flipper 调试时：NO_FLIPPER=0 pod install

# 12c. 打开 Xcode workspace
open TaroShell.xcworkspace

Xcode 打开后:

  1. 顶部 scheme 选 TaroShell
  2. 设备选 iPhone 15 / iOS 17 模拟器
  3. 点 ▶ Run

Metro 终端会检测到 i 键,自动触发 iOS 构建和启动。

完整流程图

复制代码 
1. 装 CocoaPods ────────────────┐
                                 │
2. 配 Gradle 阿里云镜像 ─────────┤
                                 │
3. init RN 0.73.11 工程 ─────────┤ 一次性的环境/工程准备
                                 │
4. 迁移 android/ ios/ ───────────┤
                                 │
5. 配 Android SDK 路径 ──────────┤
                                 │
6. 装 npm 依赖 ──────────────────┤
                                 │
7. 改 MainActivity 组件名 ───────┘
                                 │
8. gradlew tasks 验证 ───┐
                         │
9. 启动 Metro ───────────┤ 跑通阶段
                         │
10. installDebug 装到模拟器 ─┤
                         │
11. 验证 ────────────────┘
                         │
12. iOS 端(可选) ───────┘

关键命令速查

场景 命令
启动 Metro(必跑) cd /Users/username/Documents/demo && npm run dev:rn
安装到 Android 模拟器 cd android && ./gradlew installDebug
手动启动 app adb shell am start -n com.taroshell/.MainActivity
列出 adb 设备 adb devices
Metro 重新加载 Metro 终端按 r
打开 Dev Menu Metro 终端按 d,或模拟器 ⌘+M
安装 pods cd ios && pod install
清 Metro 缓存 rm -rf $TMPDIR/metro-cache-*
相关推荐
Aphasia31112 小时前
手写KeepAlive组件
前端·react.js·面试
whatever who cares16 小时前
大型 React 项目的文件结构
前端·react.js·前端框架
假如让我当三天老蒯17 小时前
useCallback 详细解释（从原理到用法）（自学用）
前端·react.js
Vu46117 小时前
nextjs的图片和文字优化
react.js
我命由我1234520 小时前
Android 开发，FragmentPagerAdapter 的 isViewFromObject 方法问题
android·java-ee·kotlin·android studio·android jetpack·android-studio·android runtime
gogoing20 小时前
React Hooks 完整指南
react.js
假如让我当三天老蒯21 小时前
State和Props区别和左右（自学用）
前端·react.js
夜雪闻竹1 天前
React Query + REST API 最佳实践
前端·react.js·前端框架
热门推荐
01GitHub 镜像站点022026 年 AI 编程工具终极横评：Cursor vs Claude Code vs Copilot vs Windsurf03Codex 下载安装指南：Windows 和 macOS 官方版下载04【AI】2026 年具身智能模型和世界模型总结05Codex 桌面端更新后 Chrome 插件和 Computer Use 不可用，怎么排查和修复06CC-Switch 下载、安装与使用配置指南【2026.5.29】07【踩坑记录 | 第一篇】微软商店无法使用时，如何手动安装 OpenAI Codex？附`.msix`文件系统错误解决方法08CC-Switch & Claude 基于 Linux 服务器安装使用指南09Codex 接入 DeepSeek API 完整配置文档10裂开！ChatGPT 居然开始要手机号验证，附详细解决方法