brands-monorepo/NativePlugins/signing-config-plugin/README.md

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

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

## 目录
- [适用范围](#适用范围)
- [功能概览](#功能概览)
- [文件结构](#文件结构)
- [环境与前提](#环境与前提)
- [接入步骤](#接入步骤)
- [工作原理](#工作原理)
- [Gradle 注入内容](#gradle-注入内容)
- [Proguard 规则](#proguard-规则)
- [构建与运行](#构建与运行)
- [常见问题](#常见问题)
- [注意事项](#注意事项)
- [验证检查清单](#验证检查清单)

## 适用范围
- 管理模式：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`：签名属性文件（示例），格式如下：
```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` 注册插件：
```js
plugins: [
  // ... 其他插件
  [
    "./NativePlugins/signing-config-plugin/app.plugin.js",
    {}
  ]
]
```
- 需要可用的 keystore 与正确的 `keystore.properties`：
  - `STORE_FILE` 相对路径为 `android/app/` 下的文件名（如 `FLink.keystore`）
  - 密钥口令需与你实际证书匹配

## 接入步骤
1. 将你的 `keystore` 与 `keystore.properties` 放入插件目录：
   - `NativePlugins/signing-config-plugin/FLink.keystore`
   - `NativePlugins/signing-config-plugin/keystore.properties`
2. 执行预构建以应用插件：
```bash
npx expo prebuild --platform android --clean
```
3. 构建或运行到设备：
```bash
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` 中插入如下片段（带注释标记）：
```gradle
// [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` 注入：
```gradle
// [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` 追加（带注释标记，幂等）：
```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
```

## 构建与运行
- 推荐流程：
```bash
# 安装依赖
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`

## 常见问题
1. 预构建后提示缺少 `keystore.properties`？
   - 确认文件已复制到 `android/keystore.properties`（插件会自动复制；若失败，请手动复制）
2. 构建报错 `Missing required property ...`？
   - 检查 `keystore.properties` 中四个关键项是否齐全且与证书一致
3. `debug` 为何也使用 `release` 签名？
   - 便于真机安装与调试（避免多套签名导致安装冲突）。如需还原，可手动修改 `buildTypes.debug` 的 `signingConfig`
4. Proguard 规则是否必须？
   - 插件追加的是华为 HMS 相关 keep 规则，通常对多家推送/更新 SDK 有益，幂等追加，安全无害
5. 插件会覆盖已有 `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` 的打包指南与你们的发布流程进行调整。