Android 签名配置插件使用手册（signing-config-plugin）

本插件用于在 Expo React Native 项目的预构建阶段，自动注入 Android 正式签名配置与必要的 Proguard 规则，免去手动编辑 app/build.gradle 与拷贝证书的繁琐步骤。文档风格参考仓库 docs 目录。

适用范围

管理模式：Expo 管理工作流（Managed）或预构建后裸工作流（Prebuild → Bare）
平台：Android
构建类型：支持 debug 与 release 均指向同一套签名（可按需调整）

功能概览

自动复制签名文件：
- 将 NativePlugins/signing-config-plugin/keystore.properties 复制到 android/keystore.properties
- 将 NativePlugins/signing-config-plugin/FLink.keystore 复制到 android/app/FLink.keystore
自动修改 app/build.gradle：
- 在 signingConfigs 中注入 release 签名配置（读取 android/keystore.properties）
- 在 buildTypes.release 中设置 signingConfig signingConfigs.release
- 在 buildTypes.debug 中设置 signingConfig signingConfigs.release（方便真机调试统一签名，可自行改回）
- 注入逻辑带幂等标记，避免重复注入或破坏原配置
自动追加 Proguard 规则：
- 向 android/app/proguard-rules.pro 追加华为 HMS 相关 keep 规则（若已存在标记则不重复追加）

文件结构

app.plugin.js：插件主文件，负责复制证书、修改 Gradle、追加 Proguard 规则
keystore.properties：签名属性文件（示例），格式如下：

# Android release signing (DO NOT COMMIT THIS FILE)
STORE_FILE=FLink.keystore
STORE_PASSWORD=12345678
KEY_ALIAS=flink
KEY_PASSWORD=12345678

FLink.keystore：示例 keystore 文件（建议替换为你自己的证书并管理密钥安全）

环境与前提

已在 app.config.js 注册插件：

plugins: [
  // ... 其他插件
  [
    "./NativePlugins/signing-config-plugin/app.plugin.js",
    {}
  ]
]

需要可用的 keystore 与正确的 keystore.properties：
- STORE_FILE 相对路径为 android/app/ 下的文件名（如 FLink.keystore）
- 密钥口令需与你实际证书匹配

接入步骤

将你的 keystore 与 keystore.properties 放入插件目录：
- NativePlugins/signing-config-plugin/FLink.keystore
- NativePlugins/signing-config-plugin/keystore.properties
执行预构建以应用插件：

npx expo prebuild --platform android --clean

构建或运行到设备：

pnpm run android -- --device
# 或构建 release
pnpm run android:prod:moce -- --variant release
pnpm run android:prod:fiee -- --variant release

工作原理

预构建阶段，插件会：
- 复制签名文件到 android/ 与 android/app/
- 读取并修改 app/build.gradle：
  - 确保存在 signingConfigs.release，并从 android/keystore.properties 读取四个关键项：
    - STORE_FILE、STORE_PASSWORD、KEY_ALIAS、KEY_PASSWORD
  - 将 buildTypes.release 与 buildTypes.debug 的 signingConfig 指向 signingConfigs.release
- 追加 HMS 相关 Proguard 规则到 android/app/proguard-rules.pro
注入过程内置幂等标记（注释），避免重复注入或破坏既有配置

Gradle 注入内容

插件在 signingConfigs 中插入如下片段（带注释标记）：

// [signing-config-plugin] signingConfigs.release start
release {
    def keystorePropsFile = rootProject.file("keystore.properties")
    if (!keystorePropsFile.exists()) {
        throw new GradleException("Missing keystore.properties at project root. Cannot sign release.")
    }
    def props = new Properties()
    keystorePropsFile.withInputStream { stream -> props.load(stream) }
    ["STORE_FILE", "STORE_PASSWORD", "KEY_ALIAS", "KEY_PASSWORD"].each { key ->
        if (!props.containsKey(key) || props.getProperty(key).trim().isEmpty()) {
            throw new GradleException("Missing required property '" + key + "' in keystore.properties")
        }
    }
    storeFile file(props.getProperty("STORE_FILE"))
    storePassword props.getProperty("STORE_PASSWORD")
    keyAlias props.getProperty("KEY_ALIAS")
    keyPassword props.getProperty("KEY_PASSWORD")
}
// [signing-config-plugin] signingConfigs.release end

同时为 buildTypes.release 与 buildTypes.debug 注入：

// [signing-config-plugin] buildTypes.release start
signingConfig signingConfigs.release
// [signing-config-plugin] buildTypes.release end

// [signing-config-plugin] buildTypes.debug start
signingConfig signingConfigs.release
// [signing-config-plugin] buildTypes.debug end

Proguard 规则

向 android/app/proguard-rules.pro 追加（带注释标记，幂等）：

// [signing-config-plugin] huawei proguard start
-ignorewarnings
-keepattributes *Annotation*
-keepattributes Exceptions
-keepattributes InnerClasses
-keepattributes Signature
-keepattributes SourceFile,LineNumberTable
-keep class com.hianalytics.android.** { *; }
-keep class com.huawei.updatesdk.** { *; }
-keep class com.huawei.hms.** { *; }
// [signing-config-plugin] huawei proguard end

构建与运行

推荐流程：

# 安装依赖
pnpm install
# 应用插件修改原生工程
npx expo prebuild --platform android --clean
# 运行到设备（debug 使用 release 签名，便于真机调试）
pnpm run android -- --device
# 构建生产包（APK 或 AAB）
pnpm run android:prod:moce -- --variant release
pnpm run android:prod:fiee -- --variant release

更多细节参见：docs/Expo React Native APK 打包指南.md

常见问题

预构建后提示缺少 keystore.properties？
- 确认文件已复制到 android/keystore.properties（插件会自动复制；若失败，请手动复制）
构建报错 Missing required property ...？
- 检查 keystore.properties 中四个关键项是否齐全且与证书一致
debug 为何也使用 release 签名？
- 便于真机安装与调试（避免多套签名导致安装冲突）。如需还原，可手动修改 buildTypes.debug 的 signingConfig
Proguard 规则是否必须？
- 插件追加的是华为 HMS 相关 keep 规则，通常对多家推送/更新 SDK 有益，幂等追加，安全无害
插件会覆盖已有 signingConfigs.release 吗？
- 若已有 release 子块，插件不会重复注入；若已有其它 signingConfig 指向，会替换为 signingConfigs.release 并加入标记

注意事项

密钥安全：
- keystore 与 keystore.properties 不应提交到公共仓库（当前示例为演示用途，正式项目请使用安全方案）
- 建议使用私有仓库/加密存储/CI 注入方式管理签名文件
预构建覆盖：
- 请不要直接在原生目录手动修改签名相关配置，下一次 prebuild 可能被插件逻辑覆盖或冲突
幂等注入：
- 插件通过注释标记实现幂等，避免多次执行导致重复片段

验证检查清单

文件复制
- android/keystore.properties 存在且内容正确
- android/app/FLink.keystore 存在
Gradle 配置
- app/build.gradle 的 signingConfigs 包含 release（带插件注释标记）
- buildTypes.release 与 buildTypes.debug 指向 signingConfigs.release（带插件注释标记）
构建产物
- ./gradlew assembleRelease 成功，生成 app-release.apk 或 app-release.aab
- 安装到设备成功（adb install 或通过 Android Studio）

如需进一步扩展或接入 CI，请结合本仓库 docs 的打包指南与你们的发布流程进行调整。

7.9 KiB Raw Blame History Unescape Escape

Android 签名配置插件使用手册（signing-config-plugin）

目录

适用范围

功能概览

文件结构

环境与前提

接入步骤

工作原理

Gradle 注入内容

Proguard 规则

构建与运行

常见问题

注意事项

验证检查清单

7.9 KiB

Raw Blame History