ibit-flutter

CoinVision Flutter App

版本信息

flutter sdk 3.41.4

Dart 3.11.1

DevTools: 2.54.1

自动化脚本

项目提供两个发版脚本,位于 scripts/ 目录:

脚本	作用
scripts/bump-version.sh	升级版本号（同步 pubspec.yaml 和 app_config.dart）
scripts/build.sh	自动打包 Android/iOS Release,归档产物和调试符号

一键发版流程

./scripts/bump-version.sh patch   # 升级修订号 (4.0.3 → 4.0.4)
./scripts/build.sh                # 同时构建 Android + iOS Release
git add pubspec.yaml lib/core/config/app_config.dart
git commit -m "chore(release): bump version to 4.0.4"
git tag v4.0.4

版本修改

版本号存放在两处,必须保持同步:

• pubspec.yaml → version: x.y.z+versionCode（Android/iOS 构建系统读取）
• lib/core/config/app_config.dart → appVersion = 'x.y.z'（Dart 运行时读取,用于后端上报和 UI 展示）

versionCode 规则: major × 10000 + minor × 100 + patch

• 例如 4.0.3 → 40003,4.1.0 → 40100,5.0.0 → 50000
• 修订号/次版本号不能超过 99,否则与下一级 versionCode 冲突
• Android 严禁 versionCode 回退,系统会拒绝安装

使用脚本自动升级（推荐）

./scripts/bump-version.sh --show        # 显示当前版本
./scripts/bump-version.sh patch         # 4.0.3 → 4.0.4
./scripts/bump-version.sh minor         # 4.0.3 → 4.1.0
./scripts/bump-version.sh major         # 4.0.3 → 5.0.0
./scripts/bump-version.sh 4.2.1         # 手动指定版本
./scripts/bump-version.sh patch --dry-run   # 预览变更,不写入文件

脚本会自动:

• 同步写入 pubspec.yaml 和 app_config.dart
• 按 major × 10000 + minor × 100 + patch 计算 versionCode
• 校验 versionCode 必须严格递增,拒绝回退
• 校验修订号/次版本号不超过 99
• 写入后验证文件内容

手动升级

如需手动改,同步修改以下两处即可:

# pubspec.yaml (第 4 行)
version: 4.0.4+40004

// lib/core/config/app_config.dart (第 50 行)
static const String appVersion = '4.0.4';

打包命令

使用脚本（推荐）

./scripts/build.sh                 # 同时构建 Android + iOS Release (默认)
./scripts/build.sh android         # 仅构建 Android Release
./scripts/build.sh android-debug   # 仅构建 Android Debug
./scripts/build.sh ios             # 仅构建 iOS Release
./scripts/build.sh ios-adhoc       # 仅构建 iOS Ad-hoc
./scripts/build.sh --clean         # 构建前执行 flutter clean

脚本会自动:

• 从 pubspec.yaml 读取版本号
• 构建时开启 Dart 混淆和符号剥离
• 归档 APK/IPA 到 releases/v<版本>_<时间戳>/
• 归档 Dart 调试符号到 releases/.../symbols-android/ 和 symbols-ios/
• 生成 BUILD_INFO.txt 记录 Git 提交、构建时间等元信息

手动命令

Android

APK 直装分发，同时覆盖 armeabi-v7a（32 位老机）和 arm64-v8a（64 位新机）。

# Debug 包（包名 com.ibit.app.test，使用 env_debug.dart 接口地址）
flutter build apk --debug --target-platform android-arm,android-arm64

# Release 包（包名 com.ibit.app，使用 env_release.dart 接口地址，正式签名）
flutter build apk --release \
  --target-platform android-arm,android-arm64 \
  --obfuscate \
  --split-debug-info=build/debug-info/android

说明：

• --target-platform android-arm,android-arm64：同时打包 32/64 位，兼容 2018 年前老机
• --obfuscate + --split-debug-info：Dart 符号混淆 + 剥离调试信息，减小包体并提升反编译难度
• 不加 --no-tree-shake-icons：让 Flutter 对 MaterialIcons-Regular.otf / CupertinoIcons.ttf 做 tree-shake，字体从 ~1.6 MB 缩到 ~30 KB

产物位置：build/app/outputs/flutter-apk/app-release.apk

ADB 安装：

adb install build/app/outputs/flutter-apk/app-release.apk

重要：build/debug-info/android/ 下的 .symbols 文件务必与 APK 一起归档，否则无法反混淆线上 Crashlytics 崩溃栈。

iOS

# Debug 包（模拟器/真机调试，使用 env_debug.dart 接口地址）
flutter run

# ad-hoc 分发包
flutter build ipa --release --export-method=ad-hoc \
  --obfuscate \
  --split-debug-info=build/debug-info/ios

# Release 包（App Store / TestFlight）
flutter build ipa --release \
  --obfuscate \
  --split-debug-info=build/debug-info/ios

说明：

• iOS 与 Android 的 --split-debug-info 目录必须分开（ios/ vs android/），否则互相覆盖
• 符号文件同样需要随 IPA 归档，用于线上崩溃栈反混淆

产物位置：build/ios/ipa/*.ipa

---

环境配置

接口地址按 debug/release 自动切换，配置文件：

环境	配置文件	触发条件
测试	lib/core/config/env_debug.dart	flutter run / flutter build --debug
生产	lib/core/config/env_release.dart	flutter build --release

也可通过 --dart-define 临时覆盖：

flutter run --dart-define=API_BASE_URL=https://custom.api.com/api/

---

包名 & Bundle ID

平台	Debug	Release
Android	com.ibit.app.test	com.ibit.app
iOS	com.ibit.app	com.ibit.app

Android debug/release 可同时安装在同一台设备上。

---

版本号

在 pubspec.yaml 第 4 行修改：

version: 4.0.3+40003
#        ^^^^^  ^^^^^
#        |      └── versionCode（Android）/ build number（iOS）
#        └── versionName / CFBundleShortVersionString

versionCode 编码规则：主版本×10000 + 次版本×100 + 修订号

• 例如 4.0.3 → 40003，4.1.0 → 40100

Android 不允许安装 versionCode 更低的包，递增即可。

---

签名

Android

• 签名文件：android/app/keystore（PKCS12 格式）
• 密码配置：android/key.properties（已加入 .gitignore）
• Release 自动使用正式签名，Debug 使用系统 debug keystore

iOS

• 通过 Xcode 自动签名管理

---

清理重建

遇到构建异常时：

flutter clean && flutter pub get