踩坑 · Flutter 构建与打包

分类：踩坑记录 → 构建与打包 覆盖：依赖、代码生成、构建失败、产物体积

---

记录格式

**症状** → **原因** → **解法** → **预防**

---

build_runner 生成 .g.dart 冲突

症状

[SEVERE] Conflicting outputs were detected...

原因 上一次生成的文件与本次冲突（常见于改了注解后重新生成，--delete-conflicting-outputs 未加）。

解法

fvm dart run build_runner build --delete-conflicting-outputs

仍不行则清理后重建：

fvm flutter clean
fvm flutter pub get
fvm dart run build_runner build --delete-conflicting-outputs

预防 把 --delete-conflicting-outputs 写进项目脚本（见 16 篇），永远别用不带该参数的 build。

---

构建卡住 / Waiting for another flutter command to release the startup lock

症状 命令长时间无响应，或提示等待锁释放。

原因 上一次 flutter 命令异常退出，锁文件未清理。

解法

# 1. 杀掉残留进程
ps aux | grep flutter        # Git Bash
# Windows: taskkill /F /IM dart.exe

# 2. 删除锁文件
rm -f $FLUTTER_ROOT/bin/cache/lockfile
# 或 fvm 管理的版本：
rm -f .fvm/flutter_sdk/bin/cache/lockfile

预防 异常中断后先检查残留进程，不要直接重跑命令。

---

命令未加 fvm 前缀导致版本不一致

症状 本地能编，CI 或同事编不过；或报"SDK version 不满足"。

原因 直接用了全局 flutter，版本与项目 .fvm/fvm_config.json 锁定版本不一致。

解法 所有命令加 fvm 前缀：

fvm flutter pub get
fvm flutter build apk --release

预防

• 项目 README 明确写出"所有命令必须加 fvm"
• IDE 的 Flutter SDK 路径指向 .fvm/flutter_sdk
• CI 里也用 fvm

---

依赖版本冲突（version solving failed）

症状

Because xxx depends on yyy >=2.0.0 and zzz depends on yyy <2.0.0, version solving failed.

原因 两个包依赖了同一个第三方包的不兼容版本区间。

解法（按序尝试）

# 1. 先看谁在依赖它
fvm flutter pub deps --style=compact | grep <包名>

# 2. 升级相关包到兼容版本
fvm flutter pub upgrade <包名>

# 3. 仍冲突 → 在 pubspec.yaml 强制指定版本（最后手段）
dependency_overrides:
  yyy: ^2.1.0

预防

• dependency_overrides 是技术债，加了要记 TODO 并尽快移除
• 引入新包前先看它的依赖约束

---

Release 包行为异常（Debug 正常）

症状 Debug 一切正常，Release 包崩溃/白屏/接口失败。

原因（按概率排序）

1. 混淆把反射、JNI、Platform Channel 相关类混淆掉了
2. Release 才生效的权限/网络配置（如 Android 网络安全配置、明文流量限制）
3. 只在 Release 暴露的时序问题（异步竞态被 Debug 的慢速掩盖）

解法

# 先用 profile 模式复现（保留部分调试能力，性能接近 Release）
fvm flutter run --profile

# 若怀疑混淆，临时关掉验证
fvm flutter build apk --release --no-shrink

确认是混淆问题后补保留规则（见 23 篇）：

-keep class io.flutter.plugin.** { *; }
-keep class com.yourpackage.** { *; }

预防 发版前必须用 Release 包完整走一遍主流程，不要只测 Debug。

---

包体过大

症状 APK 远超预期（Flutter 空包基线约 5~8MB）。

原因（按常见度）

1. 未做 ABI 分包（默认打全架构）
2. 资源未压缩（图片、字体）
3. 引入了体积大的依赖

解法

# 1. ABI 分包（立竿见影）
fvm flutter build apk --split-per-abi --release

# 2. 分析体积构成
fvm flutter build apk --analyze-size --target-platform android-arm64

# 3. 上架用 AAB（由商店按需下发）
fvm flutter build appbundle --release

# 4. 开启资源压缩与混淆
minifyEnabled true
shrinkResources true

预防

• 图片用 webp、字体子集化
• 引入新依赖前看体积影响（--analyze-size）

---

iOS 构建失败：签名 / 描述文件

症状Signing for "Runner" requires a development team 或 No profiles for 'xxx' were found。

原因 签名配置缺失或描述文件与 Bundle ID 不匹配。

解法

1. Xcode → Runner target → Signing & Capabilities → 选正确的 Team
2. 确认 Bundle ID 与开发者后台的 App ID 一致
3. flutter build ipa 时指定：--export-options-plist=ExportOptions.plist
4. CI 场景：用 fastlane match 或导入证书后 security unlock-keychain

预防

• 团队统一签名方式（自动 vs 手动）
• 证书与描述文件的有效期登记，提前续期

---

待记录

遇到新问题请按格式追加到此文件：

• [ ] flutter pub get 缓存异常导致依赖装不上
• [ ] 多 flavor 构建时的配置错误
• [ ] 国内环境 pub get 超时的镜像配置
• [ ] AAR / Framework 产物与原生工程版本不一致