flutter-template/docs/setup-android.md

Android 配置指南

本文档覆盖 Android 端从 Flavor 验证到正式签名发布包所需的全部配置步骤。

---

前提

• Android Studio Meerkat (2024.3) 或更高版本
• Android SDK：API 34（compileSdk）/ API 21（minSdk）
• JDK 17（Android Gradle Plugin 要求）
• 已完成 setup-project.md 的 Step 1–4

---

1. 验证 Flavor 构建

脚手架预配置了三个 Flavor：dev / staging / prod，对应三套应用名和包名后缀。

# 确认三个 Flavor 都能构建（debug 模式，速度最快）
make build-apk-dev          # com.example.sunny_mochi.dev

flutter build apk --flavor staging --debug \
  --dart-define-from-file=dart-defines/staging.json
# com.example.sunny_mochi.staging

flutter build apk --flavor prod --debug \
  --dart-define-from-file=dart-defines/prod.json
# com.example.sunny_mochi

若构建失败，检查 android/app/build.gradle.kts 中的 flavorDimensions 和 productFlavors 配置。

---

2. 修改包名（业务项目必须）

编辑 android/app/build.gradle.kts，找到 productFlavors 和 defaultConfig：

defaultConfig {
    applicationId = "com.your_company.your_app"   // ← 修改
    // ...
}

productFlavors {
    create("dev") {
        applicationIdSuffix = ".dev"
        // applicationId 实际为 com.your_company.your_app.dev
        resValue("string", "app_name", "YourApp Dev")  // ← 修改应用名
    }
    create("staging") {
        applicationIdSuffix = ".staging"
        resValue("string", "app_name", "YourApp Beta") // ← 修改应用名
    }
    create("prod") {
        resValue("string", "app_name", "YourApp")      // ← 修改应用名
    }
}

同步修改 android/app/src/main/AndroidManifest.xml 确认使用 @string/app_name（脚手架默认已使用）。

---

3. 配置 Release 签名

3.1 生成 Keystore（首次）

mkdir -p android/keystore
keytool -genkey -v \
  -keystore android/keystore/release.jks \
  -alias your-key-alias \
  -keyalg RSA \
  -keysize 2048 \
  -validity 10000

⚠️ Keystore 丢失无法找回，必须妥善保管。 建议：

• 备份到加密云存储（1Password / Bitwarden Vault）
• CI/CD 系统通过 secret 变量注入，不放在仓库中
• android/keystore/ 目录已在 .gitignore 中

3.2 填写 key.properties

cp android/key.properties.template android/key.properties

编辑 android/key.properties（相对于 android/app/ 目录）：

storePassword=your-keystore-password
keyPassword=your-key-password
keyAlias=your-key-alias
storeFile=../keystore/release.jks

key.properties 已在 android/.gitignore 中，不会被提交。

3.3 验证签名配置

# 构建 staging release APK（使用 release 签名）
make build-staging

# 查看签名信息
apksigner verify --print-certs \
  build/app/outputs/flutter-apk/app-staging-release.apk

---

4. 配置 Firebase（可选）

若业务项目使用 Firebase（推送通知 / Analytics）：

1. 在 Firebase Console 为每个 Flavor 创建应用（不同包名）
2. 下载各包名对应的 google-services.json，放置到对应 Flavor 目录：

android/app/src/
├── dev/google-services.json
├── staging/google-services.json
└── main/google-services.json        # prod 用 main

3. 在 android/app/build.gradle.kts 添加 Google Services 插件：

plugins {
    // ...
    id("com.google.gms.google-services")
}

4. 将 google-services.json 加入 .gitignore（含 API key，勿提交）：

# 在根 .gitignore 中添加
**/google-services.json

google-services.json 已在 android/.gitignore 中有注释行，取消注释即可。

---

5. 配置 ProGuard / R8（Release 混淆）

脚手架的 android/app/build.gradle.kts 已预启用 R8：

buildTypes {
    release {
        isMinifyEnabled = true
        proguardFiles(
            getDefaultProguardFile("proguard-android-optimize.txt"),
            "proguard-rules.pro"
        )
    }
}

android/app/proguard-rules.pro 中已预留 Drift / Sentry / Riverpod 保留规则注释，按需取消注释。

---

6. SQLCipher 注意事项

脚手架已在 build.gradle.kts 中处理 SQLCipher 的 native library 冲突：

packaging {
    jniLibs {
        pickFirsts += setOf("**/libsqlite3.so")
    }
}

若后续新增包时出现 libsqlite3.so 重复错误，在此处追加相同模式即可。

---

7. CI/CD 构建（示例：GitHub Actions）

以下为生产包构建的 workflow 关键步骤：

- name: Decode keystore
  run: |
    echo "${{ secrets.KEYSTORE_BASE64 }}" | base64 --decode \
      > android/keystore/release.jks

- name: Write key.properties
  run: |
    cat > android/key.properties <<EOF
    storePassword=${{ secrets.KEYSTORE_PASSWORD }}
    keyPassword=${{ secrets.KEY_PASSWORD }}
    keyAlias=${{ secrets.KEY_ALIAS }}
    storeFile=../keystore/release.jks
    EOF

- name: Write prod.json
  run: |
    echo '${{ secrets.PROD_DART_DEFINES }}' > dart-defines/prod.json

- name: Build AAB
  run: make build-prod

Secrets 清单：KEYSTORE_BASE64、KEYSTORE_PASSWORD、KEY_PASSWORD、KEY_ALIAS、PROD_DART_DEFINES

---

常见问题

Gradle sync 失败，报找不到 compileSdk

确认 Android SDK Platform 34 已安装（Android Studio → SDK Manager → Android 14）。

libsqlite3.so duplicate 错误

在 build.gradle.kts 的 packaging.jniLibs.pickFirsts 中追加冲突的 .so 路径。

Release APK 运行时崩溃，Debug APK 正常

通常是 ProGuard 混淆了不应混淆的类。查看 build/outputs/mapping/ 下的 seeds.txt 和 Logcat，在 proguard-rules.pro 添加对应的 -keep 规则。

签名 APK 安装时提示"应用已安装但签名不同"

设备上已安装其他签名版本，需先卸载再安装，或换测试设备。