macOS 下 React Native + TypeScript + Android 开发环境完整搭建指南

本文记录了在 macOS 系统下从零开始搭建 React Native + TypeScript 开发环境，并成功构建 Android APK 的完整过程，包含所有遇到的问题和解决方案。

项目背景

基于 STM32 的蓝牙电动小船控制系统，使用 React Native 开发移动端控制界面，支持横屏双手操作（左侧方向舵 + 右侧前进后退按钮）。

一、环境准备

1.1 系统环境

操作系统: macOS 15.6.1
Shell: Zsh
包管理器: Homebrew

1.2 必需软件版本

# Node.js 环境
node -v  # 推荐 v18+ 或 v20+

# 包管理器
npm -v   # 或使用 yarn

# JDK（重要！）
java -version  # 必须是 JDK 17-20，不支持 JDK 21

⚠️ 关键提示: React Native 0.82 构建时需要 JDK 17-20 版本，JDK 21 会导致构建失败。

二、创建 React Native 项目

2.1 初始化项目

# 进入项目目录
cd /Users/caobin/MyProjects/boat/app

# 使用最新 React Native CLI 初始化项目
npx @react-native-community/cli@latest init boat --template react-native-template-typescript

注意: 旧版命令 react-native init 已弃用，应使用 @react-native-community/cli。

2.2 项目结构

初始化后得到以下关键文件：

boat/
├── App.tsx              # 主入口文件
├── package.json         # 依赖配置
├── tsconfig.json        # TypeScript 配置
├── android/             # Android 原生代码
│   ├── build.gradle     # Android 构建配置
│   ├── app/build.gradle # App 模块配置
│   └── gradle/          # Gradle 配置
└── ios/                 # iOS 原生代码

2.3 安装项目依赖

# 安装 UI 相关依赖
npm install react-native-svg react-native-gesture-handler react-native-safe-area-context

# iOS 依赖（如需）
cd ios && pod install && cd ..

三、Android Studio 和 SDK 安装

3.1 安装 Android Studio

# 使用 Homebrew 安装
brew install --cask android-studio

# 安装完成后启动
open -a "Android Studio"

3.2 配置 Android SDK

方法一：通过 Android Studio GUI

打开 Android Studio
进入 Settings/Preferences → Appearance & Behavior → System Settings → Android SDK
在 SDK Platforms 标签下，安装：
- ✅ Android SDK Platform 35
- ✅ Android SDK Platform 34
在 SDK Tools 标签下，安装：
- ✅ Android SDK Build-Tools 35.0.0
- ✅ Android SDK Platform-Tools
- ✅ NDK (Side by side) 29.0.14206865
- ✅ CMake 3.22.1

方法二：命令行安装（更快）

# 设置环境变量
export ANDROID_HOME=$HOME/Library/Android/sdk
export PATH=$PATH:$ANDROID_HOME/emulator
export PATH=$PATH:$ANDROID_HOME/platform-tools
export PATH=$PATH:$ANDROID_HOME/cmdline-tools/latest/bin

# 使用 sdkmanager 安装
sdkmanager "platform-tools" "platforms;android-35" "build-tools;35.0.0"
sdkmanager "ndk;29.0.14206865" "cmake;3.22.1"

3.3 配置环境变量

编辑 ~/.zshrc 或 ~/.bash_profile：

# Android SDK
export ANDROID_HOME=$HOME/Library/Android/sdk
export PATH=$PATH:$ANDROID_HOME/emulator
export PATH=$PATH:$ANDROID_HOME/platform-tools
export PATH=$PATH:$ANDROID_HOME/tools
export PATH=$PATH:$ANDROID_HOME/tools/bin

# 刷新配置
source ~/.zshrc

3.4 验证安装

# 检查 adb
adb version

# 检查 SDK 路径
echo $ANDROID_HOME

# 列出已安装的 SDK
sdkmanager --list | grep "build-tools\|platforms\|ndk"

四、Gradle 配置优化

4.1 修改项目级 build.gradle

文件路径: android/build.gradle

buildscript {
    ext {
        buildToolsVersion = "35.0.0"
        minSdkVersion = 24
        compileSdkVersion = 35  // 重要：必须 >= 35
        targetSdkVersion = 34
        ndkVersion = "29.0.14206865"
        kotlinVersion = "2.1.20"
    }
    repositories {
        google()
        maven { url = 'https://maven.aliyun.com/repository/google' }
        maven { url = 'https://maven.aliyun.com/repository/public' }
        maven { url = 'https://maven.aliyun.com/repository/central' }
        mavenCentral()
    }
    dependencies {
        classpath("com.android.tools.build:gradle")
        classpath("com.facebook.react:react-native-gradle-plugin")
        classpath("org.jetbrains.kotlin:kotlin-gradle-plugin")
    }
}

allprojects {
    repositories {
        google()
        maven { url = 'https://maven.aliyun.com/repository/google' }
        maven { url = 'https://maven.aliyun.com/repository/public' }
        maven { url = 'https://maven.aliyun.com/repository/central' }
        mavenCentral()
    }
}

关键配置说明：

compileSdkVersion = 35: 必须 >= 35，因为 androidx.core 1.16.0 要求编译 SDK 35+
添加阿里云镜像源加速下载（但 google() 仍需保留在最前面）

4.2 配置 Gradle Wrapper

文件路径: android/gradle/wrapper/gradle-wrapper.properties

distributionBase=GRADLE_USER_HOME
distributionPath=wrapper/dists
distributionUrl=https\://services.gradle.org/distributions/gradle-8.13-bin.zip
networkTimeout=60000
validateDistributionUrl=false
zipStoreBase=GRADLE_USER_HOME
zipStorePath=wrapper/dists

版本选择：

Gradle 8.13（推荐）
❌ 避免使用 Gradle 9.0（与 JDK 兼容性问题）

4.3 创建 local.properties

文件路径: android/local.properties

sdk.dir=/Users/caobin/Library/Android/sdk

4.4 优化 Gradle 性能

文件路径: android/gradle.properties

org.gradle.jvmargs=-Xmx4096m -XX:MaxMetaspaceSize=512m -XX:+HeapDumpOnOutOfMemoryError
org.gradle.parallel=true
org.gradle.configureondemand=true
org.gradle.caching=true
android.useAndroidX=true
android.enableJetifier=true

五、真机调试配置

5.1 启用手机 USB 调试

以 OPPO K11 为例：

开启开发者模式：
- 设置 → 关于手机 → 版本号（连续点击 7 次）
开启 USB 调试：
- 设置 → 其他设置 → 开发者选项
- ✅ 开发者选项
- ✅ USB 调试
- ✅ 允许通过 USB 安装应用
USB 连接设置：
- 连接电脑后，手机选择 传输文件 模式
- 授权电脑的 USB 调试请求

5.2 验证设备连接

# 列出已连接设备
adb devices

# 输出示例
List of devices attached
c01b1f5a        device

5.3 端口转发（关键步骤）

# 转发 Metro 开发服务器端口
adb reverse tcp:8081 tcp:8081

六、构建和安装

6.1 启动 Metro 服务器

cd /Users/caobin/MyProjects/boat/app
npm start

6.2 构建 Debug APK

cd android
ANDROID_HOME=$HOME/Library/Android/sdk ./gradlew assembleDebug

首次构建：可能需要 3-10 分钟，会下载大量依赖。

6.3 安装到设备

# 方法一：使用 React Native CLI
npm run android

# 方法二：手动安装 APK
adb install -r android/app/build/outputs/apk/debug/app-debug.apk

6.4 生成的 APK 路径

android/app/build/outputs/apk/debug/app-debug.apk

6.5 构建 Release APK（独立运行版本）

Release 版本特性：

✅ JavaScript 代码已打包进 APK，无需 Metro 服务器
✅ 可完全离线运行，不需要 USB 连接
✅ 体积更小，性能更优
✅ 适合发布给用户使用

构建步骤：

cd android

# 清理之前的构建缓存（推荐）
rm -rf .gradle build app/build app/.cxx

# 构建 Release APK
ANDROID_HOME=$HOME/Library/Android/sdk ./gradlew assembleRelease --no-daemon

首次构建注意事项：

⏱️ 时间：首次构建约 2-5 分钟
🔄 卡顿阶段：
- 15% - CMake 配置阶段（可能持续 1-2 分钟，看似卡住但实际在后台工作）
- 34% - Kotlin/Java 编译阶段
- 61% - CMake 构建阶段
- 83% - JavaScript Bundle 打包
📊 进度会突然跳跃，这是正常现象

生成的 Release APK：

# APK 位置
android/app/build/outputs/apk/release/app-release.apk

# 查看文件大小
ls -lh android/app/build/outputs/apk/release/app-release.apk
# 输出: ~18MB (Debug 版本 ~114MB)

安装 Release APK：

# 方法一：通过 ADB 安装（推荐）
adb install -r android/app/build/outputs/apk/release/app-release.apk

# 方法二：手动传输到手机
# 1. 将 APK 文件传到手机（微信/AirDrop/USB）
# 2. 在手机上打开文件管理器
# 3. 点击 APK 文件安装
# 4. 允许"未知来源"安装（如需要）

Release 版本验证：

✅ 安装 Release APK 后
✅ 拔掉 USB 线
✅ 关闭 Metro 服务器
✅ 打开 App，应该可以正常运行

如果拔掉 USB 后 App 报错 "Unable to load script"，说明安装的是 Debug 版本，需要重新安装 Release 版本。

七、常见问题与解决方案

7.1 Gradle 版本兼容性问题

错误信息：

Exception java.lang.NoSuchFieldError: Class org.gradle.jvm.toolchain.JvmVendorSpec 
does not have member field 'org.gradle.jvm.toolchain.JvmVendorSpec IBM_SEMERU'

解决方案：

降级 Gradle 版本到 8.10.2 或 8.13
确保使用 JDK 17-20（不要用 JDK 21）

# 检查 JDK 版本
java -version

# 修改 gradle-wrapper.properties
distributionUrl=https\://services.gradle.org/distributions/gradle-8.13-bin.zip

7.2 compileSdk 版本过低

错误信息：

Dependency 'androidx.core:core:1.16.0' requires libraries and applications that
depend on it to compile against version 35 or later of the Android APIs.
:app is currently compiled against android-34.

解决方案：
修改 android/build.gradle：

ext {
    compileSdkVersion = 35  // 从 34 升级到 35
    buildToolsVersion = "35.0.0"
}

7.3 NDK 下载失败或损坏

错误信息：

[CXX1101] NDK at /Users/.../ndk/27.0.12077973 did not have a source.properties file
java.util.zip.ZipException: Archive is not a ZIP archive

解决方案：

# 1. 清理损坏的 NDK
rm -rf ~/Library/Android/sdk/ndk/*

# 2. 通过 Android Studio SDK Manager 手动下载
# Settings → SDK Tools → NDK (Side by side) → 勾选 29.0.14206865

# 3. 验证安装
ls -la ~/Library/Android/sdk/ndk/29.0.14206865/source.properties

7.4 CMake 下载失败

错误信息：

Warning: An error occurred while preparing SDK package CMake 3.22.1: 
Unexpected end of ZLIB input stream

解决方案：

# 方法一：通过 Android Studio SDK Manager 安装
# Settings → SDK Tools → CMake → Apply

# 方法二：使用 Homebrew（但 Gradle 可能无法识别）
brew install cmake

7.5 tensorflow-lite-metadata 找不到

错误信息：

Could not find tensorflow-lite-metadata-0.2.0.jar

解决方案：
确保 google() 仓库在 Maven 配置最前面：

repositories {
    google()  // 必须在最前面
    maven { url = 'https://maven.aliyun.com/repository/google' }
    mavenCentral()
}

7.6 Metro 服务器连接失败

错误信息：

Unable to load script.
Make sure you're running Metro or that your bundle 'index.android.bundle' 
is packaged correctly for release.

解决方案：

# 1. 端口转发
adb reverse tcp:8081 tcp:8081

# 2. 重启 Metro（清除缓存）
npx react-native start --reset-cache

# 3. 在手机 App 中点击 "RELOAD" 或双击 R 键

7.7 Gradle 下载慢或超时

解决方案：

# 1. 修改 gradle-wrapper.properties 增加超时时间
networkTimeout=60000

# 2. 使用镜像源（可选，但注意兼容性）
distributionUrl=https\://mirrors.cloud.tencent.com/gradle/gradle-8.13-bin.zip

# 3. 手动下载后放到缓存目录
# 下载 gradle-8.13-bin.zip 后放到：
~/.gradle/wrapper/dists/gradle-8.13-bin/[hash]/

7.8 Release 构建卡在 15% 或 CMake 配置阶段

现象：

<==========---> 15% EXECUTING [1m 30s]
> :app:configureCMakeRelWithDebInfo[arm64-v8a] > Resolve files of configuration
> :react-native-gesture-handler:configureCMakeRelWithDebInfo[arm64-v8a]
> :react-native-safe-area-context:compileReleaseKotlin
> :react-native-svg:compileReleaseJavaWithJavac

原因：

CMake 配置阶段需要解析大量依赖和编译原生代码
在后台默默工作，进度条看似卡住但实际在执行
React Native 0.82 的新架构（New Architecture）强制启用，增加了构建复杂度

解决方案：

# 1. 耐心等待（推荐）
# CMake 配置阶段通常需要 1-3 分钟，之后会突然完成并跳到 34%
# 不要急于取消构建

# 2. 减少构建架构（加速构建）
# 编辑 android/gradle.properties
reactNativeArchitectures=arm64-v8a  # 只构建 arm64（现代手机都支持）
# 原配置: armeabi-v7a,arm64-v8a,x86,x86_64

# 3. 使用 --no-daemon 避免守护进程问题
ANDROID_HOME=$HOME/Library/Android/sdk ./gradlew assembleRelease --no-daemon

# 4. 增加网络超时和并行构建配置
# 编辑 android/gradle.properties
org.gradle.workers.max=4
systemProp.org.gradle.internal.http.connectionTimeout=60000
systemProp.org.gradle.internal.http.socketTimeout=60000

构建时间参考：

配置阶段（0-15%）：10-20秒
CMake 配置（15%）：1-3分钟（看似卡住）
Kotlin/Java 编译（15-34%）：30-60秒
CMake 构建（34-61%）：20-40秒
JS Bundle 打包（61-83%）：10-20秒
最终打包（83-100%）：10-20秒

总计：首次 Release 构建约 2-5 分钟

7.9 拔掉 USB 后 App 报错无法运行

错误信息：

Unable to load script.
Make sure you're running Metro or that your bundle 'index.android.bundle' 
is packaged correctly for release.

原因：

Debug 版本的 APK 必须连接 Metro 服务器才能运行
JavaScript 代码未打包进 APK，需要实时从 Metro 加载

解决方案：

# 构建并安装 Release 版本
cd android
ANDROID_HOME=$HOME/Library/Android/sdk ./gradlew assembleRelease --no-daemon
adb install -r app/build/outputs/apk/release/app-release.apk

# Release 版本可以完全离线运行，无需 Metro 服务器

验证是否为 Release 版本：

拔掉 USB
关闭电脑上的 Metro 服务器
打开 App
✅ 如果能正常运行 → Release 版本
❌ 如果报错 → Debug 版本，需重新安装

八、项目配置示例

8.1 锁定横屏显示

文件路径: android/app/src/main/AndroidManifest.xml

<activity
  android:name=".MainActivity"
  android:screenOrientation="landscape"
  android:configChanges="keyboard|keyboardHidden|orientation|screenLayout|screenSize"
  ...>
</activity>

8.2 隐藏状态栏

文件路径: src/components/YourComponent.tsx

import { StatusBar } from 'react-native';

function YourComponent() {
  return (
    <View>
      <StatusBar hidden={true} />
      {/* 其他内容 */}
    </View>
  );
}

九、完整构建流程总结

9.1 Debug 版本（开发调试）

# 1. 环境检查
java -version           # 确保 JDK 17-20
echo $ANDROID_HOME      # 确保 SDK 路径正确
adb devices             # 确保设备已连接

# 2. 安装依赖
npm install

# 3. 启动 Metro 服务器（新终端）
npm start

# 4. 构建并安装（新终端）
npm run android

# 或分步执行：
cd android
./gradlew assembleDebug
cd ..
adb install -r android/app/build/outputs/apk/debug/app-debug.apk

# 5. 端口转发（如遇连接问题）
adb reverse tcp:8081 tcp:8081

# 6. 重新加载（在手机 App 中）
# 摇晃手机 → Reload 或 双击 R 键

9.2 Release 版本（发布/离线运行）

# 1. 环境检查（同上）
java -version
echo $ANDROID_HOME
adb devices

# 2. 清理构建缓存（推荐）
cd android
rm -rf .gradle build app/build app/.cxx

# 3. 构建 Release APK
ANDROID_HOME=$HOME/Library/Android/sdk ./gradlew assembleRelease --no-daemon

# 等待构建完成（约 2-5 分钟）
# 进度可能会在 15% 停留 1-3 分钟，这是正常的 CMake 配置阶段

# 4. 安装到手机
adb install -r app/build/outputs/apk/release/app-release.apk

# 5. 验证离线运行
# - 拔掉 USB
# - 关闭 Metro 服务器
# - 打开 App，应该可以正常运行

9.3 Debug vs Release 对比

特性	Debug 版本	Release 版本
体积	~114MB	~18MB
构建时间	1-3分钟	2-5分钟
运行方式	需要 Metro 服务器	完全独立运行
USB 连接	必须连接	无需连接
适用场景	开发调试	发布/离线使用
热重载	✅ 支持	❌ 不支持
性能	未优化	已优化

十、性能优化建议

10.1 加速依赖下载

// android/build.gradle
allprojects {
    repositories {
        google()
        maven { 
            url 'https://maven.aliyun.com/repository/google'
            // 阿里云镜像加速
        }
        maven { 
            url 'https://maven.aliyun.com/repository/public' 
        }
        mavenCentral()
    }
}

10.2 Gradle 构建加速

# android/gradle.properties
org.gradle.jvmargs=-Xmx4096m -XX:+HeapDumpOnOutOfMemoryError
org.gradle.parallel=true
org.gradle.configureondemand=true
org.gradle.caching=true
org.gradle.daemon=true

10.3 清理构建缓存

# 清理 Gradle 缓存
cd android
./gradlew clean
./gradlew cleanBuildCache

# 清理 Metro 缓存
npx react-native start --reset-cache

# 清理 npm 缓存
npm cache clean --force

十一、开发工具推荐

11.1 调试工具

# React Native Debugger
brew install --cask react-native-debugger

# Flipper（官方推荐）
brew install --cask flipper

11.2 日志查看

# Android 日志
adb logcat | grep ReactNative

# 或使用过滤
adb logcat *:S ReactNative:V ReactNativeJS:V

11.3 性能监控

在 App 中摇晃手机 → Show Perf Monitor

十二、参考资源

官方文档

常用命令速查

# 查看 React Native 版本
npx react-native --version

# 环境诊断
npx react-native doctor

# 列出已连接设备
adb devices

# 卸载应用
adb uninstall com.boat

# 清除应用数据
adb shell pm clear com.boat

# 重启 ADB 服务
adb kill-server && adb start-server

# 查看构建日志
./gradlew assembleDebug --info

总结

本文详细记录了在 macOS 下搭建 React Native + TypeScript + Android 开发环境的完整过程，包括：

✅ Android Studio 和 SDK 的正确安装配置
✅ Gradle 构建系统的优化和问题排查
✅ 真机调试的完整流程
✅ Debug 和 Release 两种版本的构建方法
✅ 常见错误的解决方案
✅ 项目配置的最佳实践

关键要点：

使用 JDK 17-20（不要用 JDK 21）
compileSdk 必须 >= 35（androidx.core 1.16.0 要求）
镜像源要合理配置（google() 保留在最前）
NDK 和 CMake 最好通过 Android Studio SDK Manager 安装
真机调试需要端口转发 adb reverse tcp:8081 tcp:8081
Release 版本构建时 CMake 配置阶段（15%）会持续 1-3 分钟，需要耐心等待
离线运行必须使用 Release 版本，Debug 版本依赖 Metro 服务器

通过以上步骤，即可成功构建并运行 React Native Android 应用！🚀

如果觉得文章对你有用，请随意赞赏

macOS 下 React Native + TypeScript + Android 开发环境完整搭建指南

http://bmap.xyz//archives/1763532829160

作者

清风飒影

发布于

2025-11-19

更新于

2025-11-19

许可协议

CC BY 4.0