React Native & Expo

下面如无特别说明，环境均指 Expo SDK 53。

Android 构建依赖

• node v23.x
• Expo SDK 53
• JDK 17
• Android SDK
  • Target API level requirements for Google Play apps since August 31 2025
    • Android 15 (API level 35) or higher
  • Android API Levels and Cumulative usage

iOS 构建依赖

• node v23.x
• Expo SDK 53
• macOS 15.5
• Xcode 16.4

断点调试

启动终端 npx expo start

构建二进制包并在虚拟机中以 debug 模式启动应用 npx expo run:android

设置调试：

• 在终端中按 j 打开 React Native DevTools
• 点击右上角齿轮图标设置按钮，打开 Settings 面板，Ignore List 中去掉勾选 Enable ignore listing 选项
• 点击右上角 X 按钮关闭 Settings 面板
• 点击 Sources 标签页 ，依次展开 127.0.0.1:8081/[metro-project]/app/path/to/you-file.tsx
• 选中目标行添加 breakpoint 即可，触发逻辑运行到目标行即可

参考 https://docs.expo.dev/debugging/tools/

构建 Android 原生应用

构建步骤，以 Android Studio 为例

• 安装 Android SDK
• 设置 Gradle
  • 在 Settings - Build, Execution, Deployment - Build Tools - Gradle
    • Gradle user Home: $HOME/.gradle or %UserProfile%/.gradle
    • Distribution: Wrapper
    • Gradle JDK: check your local JDK 17

参考 https://docs.expo.dev/guides/local-app-development/#local-app-compilation

更新静态资源

如 app logo ，需 commit 变更后，在跟目录执行 npx expo prebuild 。

虚拟机上运行

启动终端 npx expo start

a. 安装并更新 Android SDK 到最新版本 b. 更新 macOS 系统、XCode 到最新正式版本

构建二进制包并在虚拟机中启动应用

• npx expo run:android
• npx expo run:ios

默认输出目录 ./android/app/build/outputs/apk/debug/app-debug.apk

真机上运行

TBD.

加载 dotenv 环境变量

• 本地/开使用文件名 .env.local
• git 忽略名单文件 .gitignore 加上 .env*.local
• 生产使用文件名 .env

参考 https://docs.expo.dev/guides/environment-variables/

本地化

https://docs.expo.dev/guides/localization/

常用类库

• 微信 WeChat react-native-wechat-lib

常见问题

升级 Expo SDK:

npx expo install expo@latest
npx expo install --fix

Android Studio 无法构建 apk

提示错误 Could not start 'node' / node command cannot be found

修改项目设置 Android SDK 路径:

• Settings - Build, Execution, Deployment - Build Tools - Gradle
  • Gradle Projects - Gradle JDK，设置为合适的值，如 /Library/Java/JavaVirtualMachines/openjdk-17.jdk/Contents/Home

参考 https://github.com/expo/expo/issues/28309

RN 无法启动 iOS 模拟器 ERROR: No bundle URL present

关闭宿主机代理，重新构建后启动应用。

Expo SDK 53 requires XCode 16

Error Value of type "some View" has no member "onGeometryChange"

see also https://github.com/expo/expo/issues/36830

添加出口合规性密钥流程

• navigate to Info.plist
• add a key named ITSAppUsesNonExemptEncryption, value is NO

SafeAreaView

规则

1. 如果是 Stack.Screen <Stack.Screen name="xxx" options={headerShown: true} /> ， header 会自动计算高度，无需计算 safe area，如果是 headerShown=false ，则需要手动计算 safe area 。
2. 如果想完整自定义 header ，可以使用 SafeAreaView 包裹。<SafeAreaView>{yourChildren}<SafeAreaView />，yourChildren 会被自动设置 paddingTop 为 headerHight 。