React 移动端实战 · 你以为 build 完就能发？APK 签名与发布流水线里藏着三个真坑

React 移动端实战 · 你以为 build 完就能发？APK 签名与发布流水线里藏着三个真坑

各位看官，前端同学第一次往应用商店递包，十有八九会在签名这一步栽跟头。我见过最离谱的：开发机上一跑 assembleRelease 通了，传到后台却被拒，提示"签名不一致"；还有人把 keystore 提交进了 Git，密码写在 signing.gradle 里明文摆着——这都是能让你"已发布应用再也无法更新"的事故。

这篇就聊 Capacitor/React 项目里从密钥生成到出包的完整发布流水线，以及三个我亲眼见过的真坑：密钥丢了、版本降级被系统拒、混淆把原生桥接类干没了。

一、签名密钥：App 的"身份证"，丢了就完了

Android 上每个能安装到真机的 APK 都必须签名。Debug 包有系统自动生成的临时签名，但正式发布必须用你自己持有的 release 密钥。而且有个铁律：

同一个应用，一辈子只能用同一个密钥签名。密钥丢了 = 这个包名永远无法更新，只能换包名重发。

所以第一步，生成密钥库（keystore）。这是一次性动作，跑一次管二十七年：

cd /path/to/your-app

keytool -genkeypair -v \
  -keystore android/app-release.keystore \
  -alias appkey \
  -keyalg RSA \
  -keysize 2048 \
  -validity 10000 \
  -storepass 你的强密码 \
  -keypass 你的强密码 \
  -dname "CN=Example App, OU=Dev, O=Example, L=City, ST=State, C=CN"

参数说明：

• -alias：密钥别名，后面配置要引用，记牢。
• -validity 10000：有效期 10000 天，约 27 年，足够 App 走完生命周期。
• -storepass / -keypass：密钥库密码和密钥密码，设不一样的强密码并离线保管。
• -dname：证书主体信息，商店展示用，可自定义。

⚠️ 千万别把 .keystore 提交 Git。我们的 .gitignore 里已经拦了：

# Android signing keys (安全：不要提交到版本控制)
*.keystore
android/app-release.keystore

提交上去等于把家门钥匙挂在门口——任何人 clone 都能拿到你的发布身份。

二、signing.gradle：把密码从明文里救出来

密钥有了，得告诉 Gradle 用它签名。但密钥密码绝不能明文写进仓库文件。我们看真实项目的 android/signing.gradle 怎么做的：

// android/signing.gradle —— 引入方式：主工程 apply from: '../signing.gradle'
android {
    signingConfigs {
        release {
            storeFile file('../app-release.keystore')
            storePassword System.getenv('KEYSTORE_PASSWORD') ?: '123456'
            keyAlias 'appkey'
            keyPassword System.getenv('KEY_PASSWORD') ?: '123456'
        }
    }

    buildTypes {
        release {
            signingConfig signingConfigs.release
            minifyEnabled true
            proguardFiles getDefaultProguardFile('proguard-android.txt'), 'proguard-rules.pro'
        }
    }
}

两个关键点：

1. 密码走环境变量：System.getenv('KEYSTORE_PASSWORD') ?: '123456'。优先读环境变量，本地没设时退回默认值（发布流水线里由 CI 注入真实密码）。这样仓库里不落明文。
2. minifyEnabled true：Release 默认开代码混淆，APK 更小更安全——但也埋了后面第三个坑。

主工程 android/app/build.gradle 顶部一行引入即可，不把签名逻辑写进主文件，职责分离：

apply plugin: 'com.android.application'
apply from: '../signing.gradle'   // ← 引入签名配置

android {
    namespace = "com.example.app"
    // ...
}

三、一键发布脚本：把"编译→同步→打包"串成一条命令

Capacitor 项目出包有个固定顺序：先 Web 构建，再 sync 进原生工程，最后 Gradle 打包。漏掉 sync 这一步，你改的 TS/JS 根本不会进 APK。我们 package.json 的脚本把这串起来：

{
  "scripts": {
    "build": "tsc -b && vite build",
    "sync": "cap sync android",
    "apk": "pnpm build && pnpm sync && cd android && ./gradlew assembleDebug && cd ..",
    "release": "pnpm build && pnpm sync && cd android && ./gradlew assembleRelease && cd ..",
    "install-release": "adb install android/app/build/outputs/apk/release/app-release.apk"
  }
}

pnpm release 实际干四件事：

1. tsc -b —— TypeScript 类型检查，编译期就拦住低级错误；
2. vite build —— 产出生产版 Web 资源；
3. cap sync android —— 把 Web 资源和插件原生代码同步进 android/ 工程，这步不做前面白忙；
4. ./gradlew assembleRelease —— Gradle 编译签名的 Release APK。

输出位置：

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

真坑提醒：cap sync 之后如果又改了 plugins/ 下的原生 Java，必须再 sync 一次才会生效。我见过改完原生不 sync，调试半小时以为逻辑写错、其实是跑的旧代码。

四、坑一：版本降级被系统直接拒

发布前必改版本号。在 android/app/build.gradle 的 defaultConfig：

defaultConfig {
    versionCode 2        // 每次发布 +1，整数，系统只认这个
    versionName "1.0.1"  // 给人看的版本号
}

versionCode 是整数单调递增计数器，系统靠它判断是否允许覆盖安装。如果你发过 versionCode 5，新包忘了改还填 5 或退回 4，真机会报：

INSTALL_FAILED_VERSION_DOWNGRADE

而且商店也会拒收 versionCode 不递增的包。这是最容易在紧急发版时翻车的点——改完代码一兴奋，忘了把 versionCode +1。

五、坑二：密钥密码错误 / 文件丢失

两个高频报错：

Failed to read key appkey from store "...keystore":
Keystore was tampered with, or password was incorrect

Keystore file not found for signing config 'release'

前者是密码错（环境变量没注入 / signing.gradle 里默认值被改坏），后者是 app-release.keystore 不在 android/ 目录下。CI 环境尤其容易踩——本地能打包，CI 上因为没设 KEYSTORE_PASSWORD 又没放 keystore 文件，直接红。

正确做法：CI 里把 keystore 作为加密 secret 注入，密码也走 secret 变量，不要在任何明文文件里写死。

六、坑三：混淆把原生桥接类干没了（最隐蔽）

minifyEnabled true 开了 ProGuard 混淆。问题来了：Capacitor 的原生插件类（比如我们上一篇文章写的 CallLogPlugin）是通过字符串反射 + 注解被 JS 桥接层找到的。ProGuard 一看这些类"没被 Java 代码直接引用"，很可能把它们重命名甚至摇树删掉，结果就是运行时桥接失效、功能静默崩溃。

而很多项目的 proguard-rules.pro 初始是个空模板——什么 -keep 都没写：

# 默认模板，啥也没 keep
# Add project specific ProGuard rules here.

所以发布前必须补 ProGuard 规则，保住原生桥接类：

# 保住应用包名下的所有类（含自定义 Capacitor 插件）
-keep class com.example.app.** { *; }

# Capacitor 核心桥接，别动
-keep class com.getcapacitor.** { *; }

# 带 @CapacitorPlugin / @PluginMethod 注解的类与 method
-keep @com.getcapacitor.annotation.CapacitorPlugin class * { *; }
-keepclassmembers class * {
    @com.getcapacitor.annotation.PluginMethod <methods>;
}

# WebView JS 接口（如果用 addJavascriptInterface）
-keepclassmembers class * {
    @android.webkit.JavascriptInterface <methods>;
}

# 保留异常栈行号，方便线上排查
-keepattributes SourceFile,LineNumberTable
-renamesourcefileattribute SourceFile

记住一个原则：凡是靠反射/注解/字符串名被调用的类，混淆前都要 -keep。React Native、Capacitor、任何插件化框架都适用。

七、进阶：多渠道打包

要在不同商店发不同包（统计来源），用 applicationIdSuffix 给每个渠道一个独立应用 ID，但共用同一套代码和签名：

buildTypes {
    release {
        signingConfig signingConfigs.release
        minifyEnabled true
        proguardFiles getDefaultProguardFile('proguard-android.txt'), 'proguard-rules.pro'
    }
    yingyongbao {
        initWith release
        applicationIdSuffix ".yingyongbao"
    }
    huawei {
        initWith release
        applicationIdSuffix ".huawei"
    }
}

initWith release 继承 release 的所有配置（签名、混淆），只改应用 ID 后缀。打包命令：

cd android && ./gradlew assembleYingyongbao assembleHuawei && cd ..

注意：渠道包应用 ID 变了，相当于不同 App，各自独立无法互相覆盖安装，测试时要清掉旧包。

八、发布前检查清单

把这套流水线固化成一张表，发版前逐条过：

九、小结

APK 签名发布看起来就是一条命令的事，但里面藏着的三个坑——密钥丢失不可逆、versionCode 降级被拒、混淆误删桥接类——每一个都能让你在发版当天焦头烂额。核心记住三句话：

1. 密钥是身份证，备份 + 不入库 + 密码走环境变量；
2. versionCode 只增不减，发版第一件事就是 +1；
3. 开了混淆，凡是反射/注解调用的类一律 -keep。

把 signing.gradle 和检查清单存好，下次发版就是机械执行，而不是现场排雷。

相关阅读：

• React 移动端实战 · 弹层一滑，背后的列表跟着滚？移动端滚动穿透，我让 AI 改了三次才改对
• React 移动端实战 · 弱网下提交的数据说没就没？离线优先队列 + 客户端幂等，移动端补传一次说清
• Flutter Debug 红屏、Release 灰屏：你的 release-only bug，只是异常被藏起来了
• Flutter Android 构建突发红字？一个跟通知无关的库，逼你开 core library desugaring
• Flutter/Android Release 包连不上网？AndroidManifest INTERNET 权限排查实录
• Node 后端实战 · 多租户数据隔离
• React 管理后台实战 · React Query 双 key 缓存：列表与详情如何互不污染
• Flutter 401 自动刷新拦截器并发死锁：_refreshQueue 死锁根治实录
• Flutter 带 TTL 的多级缓存设计：内存+磁盘+网络三层实战
• Node 后端实战 · JWT 双密钥轮转与 token 版本号

本文由 FungLeo 主导，Deepseek 优化校阅，转发请注明首发地址，谢谢大家！