Flutter 应用构建全指南：产物位置、构建命令与发布部署（iOS & Android）

注意：部分描述内容基于特定场景，主要用于对比 iOS 和 Android 平台构建流程差异，仅供参考。

本文档详细说明 Flutter 项目（基于 fvm 管理 flutter 版本）在不同平台、不同模式下的构建产物位置、构建命令、常见问题解决方案以及从开发到发布的完整流程。

iOS 构建产物

Debug 构建

构建命令：

# 标准 Debug 构建（跳过代码签名，用于开发测试）
fvm flutter build ios --debug --no-codesign

# 带详细输出的 Debug 构建
fvm flutter build ios --debug --no-codesign --verbose

主要产物位置：

build/ios/iphoneos/Runner.app

相关构建产物目录说明：

目录路径	说明
build/ios/iphoneos/Runner.app/	iOS 应用程序包（主要产物），包含可执行文件和资源
build/ios/Debug-iphoneos/	包含编译的 .a 静态库文件和其他中间产物
build/ios/iphoneos/Runner.app/Frameworks/	Flutter 引擎框架（Flutter.framework）
build/ios/iphoneos/Runner.app/App.framework/	应用代码编译后的框架

验证构建产物：

# 查看 .app 包信息
ls -lh build/ios/iphoneos/Runner.app

# 查看 .app 包内部结构
ls -la build/ios/iphoneos/Runner.app/

# 查看 .app 包大小
du -sh build/ios/iphoneos/Runner.app

# 查看 Info.plist 配置
/usr/libexec/PlistBuddy -c "Print CFBundleShortVersionString" \
  build/ios/iphoneos/Runner.app/Info.plist

Release 构建

方法一：命令行构建（不创建 Archive）

# 构建 Release 版本的 .app（不包含 Archive）
fvm flutter build ios --release --no-codesign

注意： 使用 --no-codesign 标志只会生成 .app文件，不会创建 .xcarchive。

产物位置：

build/ios/iphoneos/Runner.app

方法二：创建 Archive（用于发布）

# 创建 Archive（推荐用于 App Store 发布）
fvm flutter build ios --release

# 或者在 Xcode 中操作
open ios/Runner.xcworkspace
# 然后选择 Product > Archive

Archive 包位置：

build/ios/archive/Runner.xcarchive

Archive 目录结构说明：

路径	说明
build/ios/archive/Runner.xcarchive/Products/Applications/Runner.app	实际的应用程序
build/ios/archive/Runner.xcarchive/dSYMs/	符号文件（用于崩溃分析）
build/ios/archive/Runner.xcarchive/Products/Applications/	应用程序包位置

导出 IPA 文件：

# 方法 1: 使用 Xcode 导出（推荐）
open build/ios/archive/Runner.xcarchive
# 在 Xcode Organizer 中选择 Export

# 方法 2: 使用命令行工具（需要配置 exportOptions.plist）
xcodebuild -exportArchive \
  -archivePath build/ios/archive/Runner.xcarchive \
  -exportPath build/ios/export \
  -exportOptionsPlist ios/exportOptions.plist

Android 构建产物

Debug 构建

构建命令：

# 标准 Debug APK 构建
fvm flutter build apk --debug

# 带详细输出
fvm flutter build apk --debug --verbose

主要产物位置：

build/app/outputs/flutter-apk/app-debug.apk

相关产物说明：

文件/目录	说明
build/app/outputs/flutter-apk/app-debug.apk	Debug APK 文件（未优化，包含调试符号）
build/app/outputs/apk/debug/	包含所有 APK 输出文件

Release 构建

构建命令：

# 标准 Release APK 构建
fvm flutter build apk --release

# 构建 Split APK（按架构分离，推荐用于非 Google Play 分发）
fvm flutter build apk --release --split-per-abi

# 构建 APK 并指定目标架构
fvm flutter build apk --release --target-platform android-arm64

主要产物位置：

# 完整 APK（包含所有架构）
build/app/outputs/flutter-apk/app-release.apk

# Split APK（按架构分离，使用 --split-per-abi 时）
build/app/outputs/flutter-apk/app-armeabi-v7a-release.apk    # 32位 ARM
build/app/outputs/flutter-apk/app-arm64-v8a-release.apk      # 64位 ARM
build/app/outputs/flutter-apk/app-x86_64-release.apk         # x86_64（模拟器）

说明： Split APK 可以减小下载体积，用户设备只会下载匹配其架构的 APK。

App Bundle (AAB) - 推荐用于 Google Play

构建命令：

# 标准 App Bundle 构建
fvm flutter build appbundle --release

主要产物位置：

build/app/outputs/bundle/release/app-release.aab

App Bundle 说明：

特性	APK	AAB (App Bundle)
分发渠道	任意渠道	仅 Google Play
文件大小	较大（包含所有资源）	较小（按需生成）
优化	无	Google Play 自动优化
签名	可选	必须签名

注意： AAB 文件不能直接安装到设备，需要上传到 Google Play Console 后由 Google 生成 APK。

常见用途

iOS

1. 在模拟器中运行

# 命令行方式（自动选择模拟器）
fvm flutter run

# 指定模拟器设备（-d 后面的参数为设备名称或者设备 uuid）
fvm flutter run -d iPhone-15-Pro

# 通过 Xcode 运行
open ios/Runner.xcworkspace
# 然后点击 Xcode 的 Run 按钮

2. 在真机上安装 Debug 版本

# 方法 1: 使用命令行直接安装
fvm flutter build ios --debug --no-codesign
fvm flutter install

# 方法 2: 通过 Xcode 安装
open ios/Runner.xcworkspace
# 在 Xcode 中选择目标设备，点击 Run 按钮

# 方法 3: 使用 ios-deploy 工具（需要安装）
brew install ios-deploy
ios-deploy --bundle build/ios/iphoneos/Runner.app

3. 生成 Archive 和 IPA（用于发布）

# 步骤 1: 创建 Archive
fvm flutter build ios --release
# 或在 Xcode 中：Product > Archive

# 步骤 2: 在 Xcode Organizer 中导出 IPA
# Window > Organizer > 选择 Archive > Distribute App

# 步骤 3: 选择分发方式
# - App Store Connect（上传到 App Store）
# - Ad Hoc（内部测试）
# - Enterprise（企业分发）
# - Development（开发测试）

Android

1. 安装到设备

# 方法 1: 使用 Flutter 命令（推荐）
fvm flutter install

# 方法 2: 使用 adb 安装特定 APK
adb install build/app/outputs/flutter-apk/app-debug.apk

# 方法 3: 替换已安装的应用
adb install -r build/app/outputs/flutter-apk/app-debug.apk

# 方法 4: 安装到多个连接的设备
fvm flutter install --all-devices

2. 分发到 Google Play

# 步骤 1: 构建 App Bundle
fvm flutter build appbundle --release

# 步骤 2: 上传到 Google Play Console
# 访问 https://play.google.com/console
# 上传 build/app/outputs/bundle/release/app-release.aab

# 步骤 3: 填充商店信息、截图等
# 步骤 4: 提交审核

3. 生成签名 APK（用于非 Google Play 分发）

# 步骤 1: 创建密钥库（首次）
keytool -genkey -v -keystore ~/upload-keystore.jks \
  -keyalg RSA -keysize 2048 -validity 10000 \
  -alias upload

# 步骤 2: 配置 android/key.properties（安全存储密钥信息）
# 步骤 3: 在 android/app/build.gradle 中配置签名
# 步骤 4: 构建签名的 Release APK
fvm flutter build apk --release

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

4. 查看设备信息

# 查看连接的设备
fvm flutter devices

# 查看设备属性
adb shell getprop ro.product.model
adb shell getprop ro.build.version.release

# 安装前检查架构兼容性
adb shell getprop ro.product.cpu.abi

构建模式对比

模式	优化	调试信息	性能	大小	使用场景
Debug	无	完整	较慢	较大	开发测试
Release	完全优化	无/最少	最快	较小	生产发布
Profile	部分优化	完整	中等	中等	性能分析

清理构建产物

如需清理所有构建产物：

# 清理所有构建产物
fvm flutter clean

# 仅清理 iOS 构建
cd ios && rm -rf build && cd ..

# 仅清理 Android 构建
cd android && ./gradlew clean && cd ..

故障排除

iOS 常见问题

1. 代码签名错误

Error: Running CocoaPods...
Error running pod install

解决方案：

# 更新 CocoaPods 仓库
cd ios && pod repo update && cd ..

# 删除 Pods 并重新安装
cd ios && rm -rf Pods Podfile.lock && pod install && cd ..

# 清理构建缓存
fvm flutter clean
fvm flutter pub get

2. 构建失败 - 派生数据问题

# 清理 Xcode 派生数据
rm -rf ~/Library/Developer/Xcode/DerivedData/*

# 清理 Flutter 构建缓存
fvm flutter clean

# 重新构建
fvm flutter build ios --release

3. 真机安装失败

# 检查设备信任设置
# 设置 > 通用 > VPN与设备管理 > 信任开发者应用

# 使用开发证书重新签名
codesign --force --deep --sign - \
  build/ios/iphoneos/Runner.app

Android 常见问题

1. 构建失败 - Gradle 错误

# 清理 Gradle 缓存
cd android && ./gradlew clean && cd ..

# 删除 .gradle 缓存
rm -rf ~/.gradle/caches/

# 重新构建
fvm flutter build apk --release

2. APK 安装失败

# 卸载旧版本
adb uninstall [package.name]

# 重新安装
adb install -r build/app/outputs/flutter-apk/app-release.apk

# 检查设备存储空间
adb shell df -h

3. 多架构冲突

# 构建特定架构的 APK
fvm flutter build apk --release --target-platform android-arm64

# 检查设备架构
adb shell getprop ro.product.cpu.abi

性能优化建议

减小应用体积

平台	优化方法	命令/配置
iOS	启用 Bitcode	Xcode Build Settings > Enable Bitcode = Yes
iOS	移除未使用的资源	使用 flutter analyze 检查
Android	启用代码混淆	在 android/app/build.gradle 中配置 minifyEnabled true
Android	使用 Split APK	flutter build apk --split-per-abi
Android	启用资源压缩	shrinkResources true in build.gradle

加速构建速度

# 启用构建缓存（首次构建慢，后续快）
fvm flutter build apk --release

# 使用多线程编译
export GRADLE_OPTS="-Dorg.gradle.daemon=true -Dorg.gradle.parallel=true"

# 禁用不必要的功能
fvm flutter build apk --release --tree-shake-icons

注意事项

1. iOS 构建环境

• iOS 构建只能在 macOS 上进行
• 需要 Xcode 和 Command Line Tools
• 需要安装 CocoaPods（brew install cocoapods）

2. 代码签名

• Debug 构建：可以使用 --no-codesign 跳过签名
• Release 构建：必须配置有效的代码签名证书
• 真机调试：需要 Apple Developer 账号

3. FVM 版本管理

• 本项目使用 FVM 管理 Flutter 版本
• 所有命令都需要加 fvm 前缀
• 查看 FVM 版本：fvm flutter --version

4. 构建性能

• 首次构建或 clean 后构建会比较慢（5-15分钟）
• 后续构建会使用缓存，速度明显提升
• 建议在高速网络和 SSD 环境下构建

5. 产物验证

• 构建完成后务必验证产物文件是否存在

• 检查文件大小是否合理（通常 Debug > Release）

• 测试安装和基本功能是否正常

相关命令速查

# iOS Debug 构建
fvm flutter build ios --debug --no-codesign

# iOS Release 构建
fvm flutter build ios --release --no-codesign

# Android Debug APK
fvm flutter build apk --debug

# Android Release APK
fvm flutter build apk --release

# Android App Bundle (用于 Google Play)
fvm flutter build appbundle --release

# 查看构建产物大小
du -sh build/

# 清理构建产物
fvm flutter clean

参考资源

• Flutter 官方文档 - 构建和发布
• iOS 构建和发布
• Android 构建和发布