React Native Android 项目：应用名称、图标与 Release 打包

本文整理自 2021 年的 React Native CLI 项目实践，适用于包含 android/ 目录的原生工程；Expo 项目不适用。React Native 和 Android Gradle Plugin 会持续变化，实际配置应以当前项目和官方文档为准。

一、先确认项目类型

本文假设项目结构类似下面这样：

my-app/
├── android/
├── ios/
├── package.json
└── node_modules/

如果项目使用 Expo，应用名称、图标和启动页通常通过 app.json 或 app.config.js 配置，不需要直接修改 android/app。

二、设置 Android 应用名称

编辑：

android/app/src/main/res/values/strings.xml

把默认名称改成自己的应用名称：

<resources>
    <string name="app_name">测试程序</string>
</resources>

项目的 AndroidManifest.xml 通常会通过 @string/app_name 引用这个值。如果修改后仍然显示旧名称，检查 android/app/src/main/AndroidManifest.xml 中的 android:label 是否指向该资源。

三、准备应用图标

Android 图标不是只放一张图片。不同分辨率通常需要放入多个 mipmap-* 目录，例如：

android/app/src/main/res/
├── mipmap-mdpi/
├── mipmap-hdpi/
├── mipmap-xhdpi/
├── mipmap-xxhdpi/
└── mipmap-xxxhdpi/

推荐使用 Android Studio 的 Image Asset 工具生成各尺寸图标，然后确认 AndroidManifest.xml 中的 android:icon 指向正确的资源，例如：

<application
    android:icon="@mipmap/ic_launcher"
    android:label="@string/app_name">
</application>

不要把图标生成网站的临时文件直接提交到仓库。提交前应检查图标在浅色、深色和不同尺寸下是否清晰，并确认没有把调试图标误放到正式构建中。

四、启动页的版本差异

启动页和应用图标不是同一件事。旧版 React Native 项目常使用第三方库或自定义 Android theme；Android 12 之后，系统启动页还有新的 API 和展示规则。

因此不要直接复制旧项目的启动页代码。应先确认项目使用的 React Native 版本、Android Gradle Plugin 版本和启动页库版本，再按照对应库的安装文档配置。本文只覆盖应用名称、图标和 Release 打包，不把某个旧版启动页方案当成通用方案。

五、生成 Release APK

先进入 Android 工程：

cd android

首次执行时如果脚本没有执行权限，可以执行：

chmod +x gradlew

构建 Release APK：

./gradlew assembleRelease

成功后通常可以在下面的位置找到 APK：

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

构建前建议先清理旧产物：

./gradlew clean
./gradlew assembleRelease

六、正式签名的注意事项

测试 APK 和正式发布 APK 不应使用同一套临时密钥。正式项目应创建自己的 keystore，并在 CI 或本机安全配置签名信息：

keytool -genkeypair -v \
  -keystore my-upload-key.keystore \
  -alias my-upload-key \
  -keyalg RSA \
  -keysize 2048 \
  -validity 10000

keystore、密码和签名配置不要提交到 Git。可以放在本机的 ~/.gradle/gradle.properties、CI Secrets 或其他受保护的配置中，并在 build.gradle 中读取环境变量。

七、常见问题排查

修改名称后没有生效

• 检查修改的是 android/app 下的 strings.xml，不是其他模块的资源文件。
• 检查 Manifest 的 android:label 是否引用了正确的资源。
• 卸载旧 APK 后重新安装，避免桌面启动器缓存旧名称。

图标仍然是默认图标

• 检查 android:icon 的资源名。
• 确认各个 mipmap-* 目录中没有旧文件。
• 卸载应用后重新安装，而不是直接覆盖安装。

Release 构建失败

• 先查看 Gradle 输出中的第一个真正错误。
• 检查 Java、Gradle、Android Gradle Plugin 与 React Native 版本是否匹配。
• 不要只根据最后一行 BUILD FAILED 判断原因。

总结

应用名称、图标、启动页和 Release 签名是四个不同的问题。本文最初只是几条配置记录，补充后可以作为 React Native CLI Android 项目的基础排查清单；但对于新版本项目，仍应以当前 React Native 和 Android 官方文档为准。