Flutter 打包发布全指南：Android 与 iOS 签名构建及自动化流程

做 Flutter 这几年我越来越觉得App 开发里最讲究“艺术感”的部分往往不在花哨的 UI 和流畅的动画而在最后那一下——把几万行 Dart 代码变成用户手机里能装、能跑、能上架的安装包。Android 和 iOS 的打包流程一个是命令行加 Gradle一个是 Xcode 加证书配置看起来完全两套玩法实际操作起来每位开发者手里都有一本自己的“踩坑笔记”。这篇文章就把 Flutter 发布环节里最核心的 Android 与 iOS 打包流程完整梳理一遍。从签名机制、构建命令、证书描述文件到常见报错和自动化脚本尽量把每一步背后的“为什么”也讲清楚。新人可以照着直接复现做过一两轮发布的老手也能在这里查漏补缺省得每次发布都临时百度。1. 发布前一定要想清楚的几件事打包不是最后一步敲个命令那么简单。很多发布事故其实在环境准备阶段就埋下了。所以在真正执行flutter build之前先把几件基础的事捋顺后面的流程才会顺。1.1 Flutter版本和本机开发环境之间是连锁关系Flutter 的 SDK 版本、Dart 版本、Android Gradle PluginAGP版本、Kotlin 版本、Xcode 版本这几样东西就像连锁齿轮任何一个版本不匹配构建过程都会给你点颜色看看。最常见的一条报错就是The current configured Flutter SDK is not known to be fully supported.这个提示虽然不是致命错误但它背后往往意味着你当前项目依赖的 Gradle 插件版本不在当前 Flutter 官方验证过的兼容列表里。很多人看到这个提示选择忽略结果后续构建时跑出各种奇怪的问题比如 Kotlin 编译失败、AGP 8.x 要求升级 Gradle 版本等。建议每一次发布前都先跑一遍flutter doctor -vflutter doctor会一次性检查 Flutter SDK、Dart、Android toolchain、Xcode、CocoaPods 等环境组件的匹配情况。如果检查中有感叹号或者红色叉号先解决它再往下走。另外要特别注意 Android 项目里的android/settings.gradle。早期 Flutter 项目习惯在模块里用apply脚本方式接入 Flutter Gradle 插件新版本会提示You are applying Flutters main Gradle plugin imperatively using the apply script这是提醒你把 Flutter Gradle 插件改成声明式引入方式。处理起来也不复杂打开android/settings.gradle改成如下形态pluginManagement { def flutterSdkPath { def properties new Properties() file(local.properties).withInputStream { properties.load(it) } def flutterSdkPath properties.getProperty(flutter.sdk) assert flutterSdkPath ! null, flutter.sdk not found in local.properties return flutterSdkPath }() includeBuild($flutterSdkPath/packages/flutter_tools/gradle) repositories { google() mavenCentral() gradlePluginPortal() } } plugins { id dev.flutter.flutter-plugin-loader version 1.0.0 id com.android.application version 8.1.0 apply false id org.jetbrains.kotlin.android version 1.8.22 apply false }这样声明之后再执行flutter build插件加载方式会干净很多。版本匹配这件事官方给的兼容区间我建议直接用别自己拍脑袋升 AGP。1.2 签名证书不是Keytool一步就结束的打包前另一个必须想清楚的事是签名。签名相当于你的 App 数字身份证Android 和 iOS 都有但机制差异很大。Android 签名用 JKS 或 keystore 文件是为了验证 App 是你的同时保证版本更新时系统能识别同一个开发者。签名方案从 v1 到 v4现在新包默认会使用 v2 签名高版本 Android 安装速度更快、校验更严格。v1 主要是兼容 Android 7.0 以下的老设备如果你还打算覆盖这些设备就得在 Gradle 里把v1SigningEnabled和v2SigningEnabled都打开。v3 支持密钥轮换v4 用于 Google Play 的增量安装一般由构建工具自动处理不用手动介入。iOS 签名则更像“钥匙串”。Apple 会给你签发一颗证书代表你的开发者身份同时还会有一张描述文件Provisioning Profile里面记录了 App ID、证书、测试设备等权限信息。App 要装上真机或者上传 App Store二者缺一不可。很多新手把证书和描述文件混为一谈导致打包时反复报No signing certificate或Provisioning profile doesnt match。签名不是一次配好永远不动的。证书有效期、描述文件里的设备列表、App ID 是否匹配任何一个过期或对不上打包阶段就会立刻报错。这也是为什么我建议在第一阶段就把环境、签名方式全部理清后面才谈得上流程化发布。2. Android端打包命令行敲出AAB和APKAndroid 打包是 Flutter 发布链路里相对可控的一环毕竟命令行工具链比较成熟。下面按签名配置、构建命令、问题排查三个维度展开。2.1 签名文件生成和Gradle签名配置先在本地生成 keystorekeytool -genkey -v -keystore release.jks -keyalg RSA -keysize 2048 -validity 10000 -alias release执行时会让你填写组织信息、城市等建议如实填写后续证书指纹会依赖这些信息。生成之后release.jks就是你的核心资产要像保管密码一样保管好最好加一层本地加密备份。然后在项目根目录创建key.propertiesstorePassword你的密码 keyPassword你的密码 keyAliasrelease storeFile/绝对路径/release.jks再打开android/app/build.gradle在android块里配置签名def keystoreProperties new Properties() def keystorePropertiesFile rootProject.file(key.properties) if (keystorePropertiesFile.exists()) { keystoreProperties.load(new FileInputStream(keystorePropertiesFile)) } android { compileSdk 34 defaultConfig { applicationId com.example.yourapp minSdk 21 targetSdk 34 versionCode flutterVersionCode.toInteger() versionName flutterVersionName } signingConfigs { release { keyAlias keystoreProperties[keyAlias] keyPassword keystoreProperties[keyPassword] storeFile keystoreProperties[storeFile] ? file(keystoreProperties[storeFile]) : null storePassword keystoreProperties[storePassword] } } buildTypes { release { signingConfig signingConfigs.release minifyEnabled true shrinkResources true proguardFiles getDefaultProguardFile(proguard-android.txt), proguard-rules.pro } } }这里有一个很多人忽略的点key.properties一定要加入.gitignore。否则一旦仓库泄露别人就能用你的签名文件伪造你的 App 更新这是很严重的安全事故。minifyEnabled和shrinkResources默认是关闭的Flutter 官方模板并不强制开启。开启后体积会明显变小但可能会引入反射类、Native 方法找不到等混淆问题。如果你使用了第三方 SDK需要手动在proguard-rules.pro里补充 keep 规则。宁可体积大一点也不要上架后某个功能突然崩掉。2.2 三种构建命令怎么选Flutter 提供多个构建命令主要区别在于产物格式flutter build apk --release这条命令打出一个通用的 APK包含所有 CPU 架构的代码。优点是方便直接装到各种机型缺点包很大。适合给测试或临时分发。flutter build apk --release --split-per-abi按 CPU 架构拆分产物输出arm64-v8a、armeabi-v7a、x86_64三种 APK。现在是主流做法因为绝大多数新机型都是arm64-v8a只需要上架这一个包即可。flutter build appbundle --release这条命令生成 AABAndroid App Bundle这是 Google Play 商店要求的默认上传格式。AAB 不是直接安装包而是由 Google Play 根据用户设备的 CPU 架构、语言、屏幕密度动态生成并下发最合适的 APK。这也是最新 Flutter 版本里官方更推荐的发布方式。构建完成后产物在build/app/outputs/目录下。APK 在flutter-apk子目录AAB 在bundle/release子目录。如果要做多渠道或环境区分别直接改代码用--dart-defineflutter build apk --release --dart-defineAPI_BASE_URLhttps://api.example.com代码里通过String.fromEnvironment(API_BASE_URL)拿到这个值。这个方式比--flavor简单而且在打多个环境包时非常方便。2.3 Gradle构建失败的常见“根因”Gradle 构建失败可以排在 Flutter 发布事故榜第一名。表面报错五花八门根因其实非常集中。第一是依赖下载问题。SocketException、Connection reset、Could not resolve这类报错大概率是 Gradle 无法正常从 Google Maven 或 Maven Central 拉取依赖。这时候需要给仓库配置镜像。在android/settings.gradle的仓库列表里加上maven { url https://maven.aliyun.com/repository/google } maven { url https://maven.aliyun.com/repository/gradle-plugin } maven { url https://maven.aliyun.com/repository/public }镜像仓库能解决一大部分网络问题但不是万能。如果本地 Gradle 缓存已经损坏直接清理cd android ./gradlew clean rm -rf ~/.gradle/caches然后重新构建。注意不要轻易rm -rf整个 Gradle 目录否则后面所有项目都要重新下载依赖非常耗时。第二是 AGP 和 Gradle 版本匹配问题。错误信息里通常会带一段官方版本对照表。比如 AGP 8.1 需要 Gradle 8.0AGP 8.3 需要 Gradle 8.4。修改android/gradle/wrapper/gradle-wrapper.properties里的 distributionUrl 和android/settings.gradle里的 AGP 版本保证匹配。第三是 NDK 版本冲突。如果项目用到了带原生代码的插件报错经常是NDK Version is not supported, or doesnt match the required NDK.在android/app/build.gradle中显式指定android { ndkVersion 25.1.8937393 }版本号要和项目实际需要的 NDK 一致一般以插件文档或flutter doctor提示为准。第四是 Kotlin 编译器版本问题。Flutter 新版模板对 Kotlin 版本有最低要求如果插件来自旧项目或老仓库容易冲突。把 Kotlin 插件版本统一升级到当前 Flutter 模板对应的版本同时清理 Gradle 缓存再试。3. iOS端打包证书、描述文件和Xcode配合iOS 打包比 Android 更依赖图形环境但也别怕。只要把证书、描述文件、Xcode 三个角色理清命令行一样能完成大部分流程。3.1 打好基础Xcode与CocoaPods环境iOS 打包只能在 macOS 上做这一点绕不过去。Xcode 必须装而且建议装 App Store 里最新的稳定版。安装完成后先执行sudo xcode-select -s /Applications/Xcode.app/Contents/Developer sudo xcodebuild -license accept如果不指定 Xcode 路径后续xcodebuild命令可能拿到 Command Line Tools 而不是完整 Xcode导致构建时找不到 SDK。这个坑很隐蔽我踩过一次后每次都先确认。接着是 CocoaPods。Flutter 插件在很大程度上依赖 CocoaPods 管理原生库执行构建时 Flutter 工具会自动调用pod install但本机没有安装 CocoaPods 时就会失败。安装方式sudo gem install cocoapods或者用 Homebrewbrew install cocoapods然后进入ios目录执行pod install --repo-update如果 Pods 仓库长期不更新会搜索不到新版本插件。构建 iOS 包之前手动执行这一步能避免很多玄学问题。3.2 在Apple后台配好“门禁卡”iOS 签名需要的核心资源是证书和描述文件。首先在 Apple Developer 后台developer.apple.com注册 App ID。Bundle Identifier 必须和 Xcode 项目中配置的一致。Xcode 默认使用的 Bundle Identifier 是com.example.yourapp上架前一定要改成你自己的域名反写否则后面发布阶段会被驳回。然后是证书。在本地钥匙串访问里请求证书签名文件上传到 Apple 后台生成开发或发布证书再下载双击安装。开发证书用于真机调试发布证书用于 App Store 或 Ad Hoc 分发。描述文件的作用是把 App ID、证书、设备这三者绑定。开发描述文件需要添加测试设备的 UDIDAd Hoc 描述文件也需要设备列表最多支持 100 台App Store 描述文件不需要设备因为 App Store 分发不面向指定设备。很多人会卡在描述文件类型选错导致 Xcode 一直提示 provisioning profile doesnt include signing certificate。在 Xcode 里打开ios/Runner.xcworkspace进入Runner目标的Signing Capabilities页面选择你的 Team并确保 Bundle Identifier 正确。Xcode 的自动签名可以管理证书和描述文件但如果你要跑 CI我更建议手动生成稳定配置配合后文的 ExportOptions.plist。3.3 Archive和IPA导出实操先打一个不带签名的 release 包用来验证代码是否能通过编译flutter build ios --release --no-codesign这一步会把 Dart 代码编译成 iOS 原生产物但不会签名。如果这一步失败问题基本在你自己的代码或插件兼容性上和证书无关。确认编译通过后再用签名导出flutter build ipa --release --export-options-plistExportOptions.plistExportOptions.plist是导出的关键配置文件内容大概长这样?xml version1.0 encodingUTF-8? !DOCTYPE plist PUBLIC -//Apple//DTD PLIST 1.0//EN http://www.apple.com/DTDs/PropertyList-1.0.dtd plist version1.0 dict keymethod/key stringapp-store-connect/string keyteamID/key string你的TeamID/string keysigningStyle/key stringmanual/string keystripSwiftSymbols/key true/ keydestination/key stringexport/string /dict /plistmethod会根据分发方式变化app-store-connect是 App Store 上传ad-hoc是内部分发development是开发调试。TeamID 可以在 Apple Developer 后台 Membership 页面找到。如果不想写命令也可以用 Xcode 的 Archive 界面操作。先在 Xcode 里选择Any iOS Device (arm64)作为编译目标然后菜单栏选Product - Archive归档完成后在 Organizer 里点击Distribute App按向导选择发布方式。命令行方式更适合脚本化界面方式更适合单次手动发布两种方法生成的产物一样。3.4 分发的三种方式Development/AdHoc/AppStore很多人在打包 iOS 时不知道该选哪种方式这里简单区分。Development 包用于真机开发调试描述文件绑定开发证书和指定设备装了之后可以在 Xcode 调试器里直接连也可以自己安装。Ad Hoc 包用于分发测试描述文件同样绑定设备列表但使用发布证书签。它可以让你在不上架 App Store 的情况下把 App 发给测试同事只要他们的 UDID 在描述文件里即可上限 100 台。App Store 包通过 TestFlight 分发。先用 App Store Connect 上传 IPA然后在 TestFlight 里邀请内部测试员或外部测试员审核通过后测试员就能安装。这也是正式发布前的必经之路。三者的核心差异一个是设备限制一个是证书类型还有一个是是否经过苹果服务器。常见的错误是在某个method下使用了错误的描述文件Xcode 会直接报No profiles for ...。遇到这种问题去 Apple Developer 后台检查该描述文件关联的 App ID、证书和 device 列表是否完整。4. 打包前的代码收尾图标、版本号、启动页和权限打包流程本身顺了不代表发布就顺。我见过很多项目明明打包成功上传后被商店审核打回原因就是版本号没对齐、图标不规范、启动页黑屏这种“小问题”。发布前一定要做好收尾。4.1 版本号必须从pubspec开始统一Flutter 项目的版本号定义在pubspec.yamlversion: 1.2.34前面是面向用户的版本名比如1.2.3后面是构建号用于商店识别同一版本的不同构建必须递增。Android 打包时Gradle 会通过flutterVersionCode和flutterVersionName自动读取这个值对应 Android 的versionCode和versionName。iOS 同理1.2.3对应CFBundleShortVersionString4对应CFBundleVersion。如果你在 iOS 的 Xcode 项目里手动改过版本号然后又回pubspec.yaml改两者很容易不一致导致上传 App Store 时提示版本冲突。我的习惯是只改pubspec.yaml然后重新运行构建命令让 Flutter 工具自动同步原生工程。iOS 项目如果没有同步可以用命令手动更新cd ios /usr/libexec/PlistBuddy -c Set :CFBundleShortVersionString 1.2.3 Runner/Info.plist /usr/libexec/PlistBuddy -c Set :CFBundleVersion 4 Runner/Info.plist4.2 图标和启动图这种“小地方”最容易拖后腿Android 和 iOS 对图标尺寸要求都很碎手动一张张切图不现实。推荐用flutter_launcher_icons包。在pubspec.yaml里配置dev_dependencies: flutter_launcher_icons: ^0.13.1 flutter_launcher_icons: android: true ios: true image_path: assets/icon/app_icon.png然后执行dart run flutter_launcher_icons:main这个工具会帮你生成一套适配 Android 和 iOS 的图标。注意源图最好使用1024x1024的 PNG且不要带透明通道否则 iOS 上会被拒绝。启动图也很关键。Flutter 默认在 iOS 上使用LaunchScreen.storyboard如果配置不对会出现启动时白屏或黑屏几秒钟。iOS 项目里打开Runner/Base.lproj/LaunchScreen.storyboard把背景色和 Label 设置对即可。Android 端启动图默认由drawable/launch_background.xml控制按需求调整背景色不用强行加真图。4.3 发布包里的权限配置网络和ATS开发时用调试包网络请求通常没问题但发布包对权限要求更严格。Android 上如果你的 App 需要访问网络一定要在android/app/src/main/AndroidManifest.xml里声明uses-permission android:nameandroid.permission.INTERNET/否则上架后用户安装包无法联网只能干瞪眼。iOS 上从 iOS 9 开始强制要求 ATSApp Transport Security默认不允许 HTTP 明文请求。如果接口还没全部切到 HTTPS发布包需要在Info.plist里加keyNSAppTransportSecurity/key dict keyNSAllowsArbitraryLoads/key true/ /dict注意NSAllowsArbitraryLoads设为true是全局放开审核可能会要求补充说明。更稳妥的做法是对特定域名放开一个例外。这也是一个典型的“打包成功但线上功能异常”的隐藏原因。另外Android 高版本还会涉及FileProvider。如果你在 Flutter 里通过内部文件路径做分享、下载安装 App可能会遇到类似content://com.tencent.wework.fileprovider/external_path/...这类报错其实是文件分享授权冲突。解决方式是在AndroidManifest.xml里配置统一的FileProvider并自定义authorities避免和其他应用互相干扰。5. 自动化打包与发布后问题速查手工打包一两次可以长期维护就必须上自动化。这里分享一套足够简单的自动化思路以及我在实际项目中积累的问题排查速查表。5.1 用FASTLANE把两条打包链路统一起来Fastlane 是跨端发布自动化工具可以用一套脚本同时处理 Android 和 iOS。安装brew install fastlane在项目根目录创建fastlane/Fastfile内容类似lane :android_release do gradle( task: bundleRelease ) end lane :ios_release do build_app( scheme: Runner, export_method: app-store ) end然后执行fastlane android_release fastlane ios_releaseFastlane 还可以自动管理证书、自动上传 TestFlight、自动截图。不过证书自动管理需要额外配置如果团队规模不大我建议证书仍然手动维护但构建和上传交给 Fastlane这样最省心。除了 Fastlane简单的 Shell 脚本也能达到目的。我常用下面这组命令完成发布前的干净构建flutter pub get flutter clean flutter build appbundle --release flutter build apk --release --split-per-abiflutter clean会删除build目录和部分中间产物确保不会因为旧缓存导致莫名其妙的问题。这个习惯我从开始推广给团队后构建稳定性提升非常明显。5.2 问题速查表以下是几个最容易遇到的打包问题直接按表格查比看满屏报错日志更高效。问题现象常见原因解决步骤Gradle 下载依赖时SocketException网络访问 Google Maven 不稳定配置阿里云镜像仓库清理~/.gradle/cachesCurrent Flutter SDK is not fully supportedAGP 或 Kotlin 版本和 Flutter 版本不匹配flutter upgrade更新 AGP 到官方兼容版本iOS 构建时提示CocoaPods not installed本机缺少 CocoaPodssudo gem install cocoapods或brew install cocoapodsXcode 报No profiles for ...描述文件类型或绑定设备列表不对检查 App ID、证书、设备绑定关系重新生成描述文件上传 IPA 后 TestFlight 提示缺少图标图标尺寸或者 Alpha 通道问题用flutter_launcher_icons重新生成源图改为不透明 PNG发布包请求网络失败Android 缺少 INTERNET 权限或 iOS 未配 ATS检查AndroidManifest.xml和Info.plistFlutter 使用 Impeller 在部分老设备上花屏新版 Flutter 默认渲染引擎兼容性iOS 在Info.plist加FLTEnableImpellerfalseAndroid 在 Manifest 里关掉 Impeller启动页黑屏或白屏时间过长启动图配置不对或 Native 初始化慢配置 LaunchScreen.storyboard简化原生启动逻辑Android 文件分享路径报 FileProvider 冲突多个 SDK 的authorities冲突在 Manifest 自定义FileProvider修改authorities名称5.3 我的几个“打包前必做”习惯最后分享几个我自己的习惯谈不上严谨规范但对发布稳定性帮助很大。第一个发布包一定要用--obfuscate加--split-debug-info。这两个参数是配合使用的会把 Dart 代码做混淆并把调试符号单独输出到指定目录。flutter build appbundle --release --obfuscate --split-debug-infobuild/symbols这样即使 Datt 代码被逆向关键业务逻辑也没那么容易暴露。调试符号文件要留好一旦线上崩溃用 Firebase Crashlytics 这类工具还原 StackTrace 时会用到。没有符号文件混淆后的报错看起来就是一堆无意义的缩写排查问题会非常痛苦。第二个不要在 Debug 模式下测一下就发版。Debug 包走的是 JIT 编译性能、启动速度、崩溃行为都和 Release 包不同。至少发布前要装一遍flutter build apk --release打出来的包把核心流程走一遍。第三个如果项目要支持老设备Android 上尽量保留armeabi-v7a或直接用 AAB 让商店动态分发。x86_64主要留给模拟器用上架包可以不包含。iOS 上最低版本建议跟随 Flutter 官方支持范围过低版本会造成插件兼容问题过高版本又会丢掉一批用户最好用统计数据来定。我在实际项目中踩过最多的一次坑是 iPhone 备用机升级 iOS 后证书失效导致描述文件全部重签。后来我养成一个习惯每次发布前先登录 Apple Developer 后台把证书到期时间和设备列表检查一遍再进 Xcode 跑 Archive。这套流程看起来繁琐但它能让你在发布当天从容很多而不是在提审前夜因为签名问题手忙脚乱。