Flutter 新版本发布实战：完整安装包与 Shorebird 热更新

#一、先判断该发完整包还是补丁

判断依据是最终产物的变化。修改 pubspec.yaml 里的依赖，并不意味着一定能热更新；一个看起来只在 Dart 中调用的插件，可能也包含原生代码。Shorebird 会检查原生和资源差异，不应为了绕过检查直接使用 --allow-native-diffs 或 --allow-asset-diffs。更新范围与限制

#二、理解基础版本与补丁编号

假设 pubspec.yaml 中已有：

复制version: 1.0.0+1

1.0.0 是对用户展示的版本名称，+1 是构建号。Android 对应 versionName 和 versionCode，iOS 对应 CFBundleShortVersionString 和 CFBundleVersion。发布新的完整包时，要设置合适的新版本和递增的构建号，例如 1.1.0+2。Android 版本配置、iOS 版本配置

热更新则在基础版本下增加补丁编号，例如：

复制基础版本 1.1.0+2
  ├─ 补丁 1：修正文案
  └─ 补丁 2：修复筛选逻辑

发布补丁时，保持目标基础版本的版本号不变，并明确指定 --release-version。补丁 2 的代码应包含仍需保留的补丁 1 修复，不能把补丁理解成会按顺序逐个执行的数据库迁移脚本。多个基础版本需要分别维护、构建和验证适用补丁；给 1.1.0+2 发布补丁，不会自动更新还停留在 1.0.0+1 的安装。创建补丁

#三、首次接入只做一次

已经接入并发布过基础包的项目，可以跳过本节。

先按官方说明安装 CLI，再登录并初始化：

复制shorebird login
shorebird init --display-name "Example App"
shorebird doctor

init 会生成真实 app_id，写入 shorebird.yaml，并把该文件加入打包资源。保留生成的配置，日常发布不需要重复初始化，更不要随意执行 init --force 创建另一套应用标识。app_id 本身不是密码，可以提交配置；登录凭证、API token 和签名私钥应单独管理。初始化说明

本文示例应用通过 shorebird_code_push 自己检查和下载更新，因此配置了 auto_update: false，避免与默认自动更新流程重复运行。这不是所有项目都必须设置的选项：关闭默认更新后，应用代码必须负责调用更新 SDK。

#四、完整包发布：构建只是其中一步

#1. 整理待发布代码并运行检查

确认代码已保存，检查改动和依赖锁文件。通用检查可以使用：

复制flutter pub get --enforce-lockfile
dart format --output=none --set-exit-if-changed lib test
flutter analyze --fatal-infos
flutter test
git diff --check

项目已有统一检查脚本时，以项目脚本为准。格式命令报告失败时，先修复格式再重新检查。依赖镜像与锁文件来源不一致时，使用项目约定的包源，避免通过无关的依赖升级解决环境问题。

完整包发布还应记录代码提交、依赖锁文件、Flutter SDK 版本和构建参数。构建成功只说明产物生成成功，不能代替设备验收。

#2. 增加版本号，确认签名

例如把 pubspec.yaml 改成：

复制version: 1.1.0+2

Android 要配置自己的正式 release 签名；不能把开发签名测试包直接当成正式交付。覆盖安装需保持同一应用标识，并满足签名兼容要求。签名不匹配时，不应通过卸载旧应用“解决”问题，因为这可能丢失本地数据。密钥文件和签名密码不要提交到仓库。Android 签名说明

iOS 需要相应的开发者账号、证书、描述文件及 Xcode 签名配置。未签名构建通过，不能证明 IPA 可以安装或提交商店。iOS 发布前提

#3. 用 Shorebird 构建并注册基础包

先核对项目固定的 SDK 是否受支持：

复制shorebird flutter versions list
shorebird doctor

下面的 3.47.7 只是示例，应替换为项目实际固定并经核实受支持的版本。

Android 分发 APK：

复制shorebird release android --flutter-version 3.47.7 --artifact apk

Android 面向 Google Play 构建 AAB：

复制shorebird release android --flutter-version 3.47.7

iOS：

复制shorebird release ios --flutter-version 3.47.7

以上是按平台和分发方式选择的命令示例，不要针对同一平台、同一版本依次重复注册基础版本。需要 APK 或 AAB 时先确定交付方式，并以 CLI 输出的产物路径为准。

shorebird release 会构建应用并向 Shorebird 注册补丁基准；接下来仍需把安装包交给用户，或者提交对应应用商店。普通 flutter build 产物不能代替带 Shorebird 引擎的基础包。基础版本发布说明

#4. 安装、验收、分发

先在测试设备上覆盖安装正式签名的候选包，确认启动、核心功能、登录态和本地数据正常。核对支持的 CPU 架构：仅 arm64 的包不能作为所有 Android 设备都能安装的证明。

APK 走自己的可信分发渠道；AAB 提交 Google Play；iOS 先经 TestFlight 或适用的测试方式验收，再提交 App Store。应用商店上传、审核和正式发布是后续步骤，不能仅凭 Shorebird 显示 release 成功就宣布已上架。

分发时交付注册基础版本所对应的产物，避免之后又用另一套工具或不同参数重建一份同版本包，导致用户安装包与补丁基准不一致。

#五、日常补丁发布：保持基础版本号不变

以下假设用户已经安装 1.1.0+2 的 Shorebird 基础包，且改动只涉及可补丁化的代码。

#1. 修改代码并检查

修复问题，运行项目检查，确认此次改动没有原生或资源变化。保持 version: 1.1.0+2，使用对应基础包的 Flutter 版本，并保持 flavor、入口文件及必要的构建参数一致。

#2. 构建验证，再发布到目标通道

可先进行不上传的构建验证：

复制shorebird patch android --release-version 1.1.0+2 --dry-run

需要直接面向正式用户发布时：

复制shorebird patch android --release-version 1.1.0+2 --track stable

iOS 有自己的基础版本和补丁，需单独处理：

复制shorebird patch ios --release-version 1.1.0+2 --track stable

Android 成功不代表 iOS 同步成功。执行上传确认前，要核对 CLI 展示的应用、平台、目标版本和通道。发布 stable 后，匹配该基础版本和通道的用户设备就可能收到补丁。补丁命令与参数

#3. 有预发布能力时，先 staging，再 stable

正式用户较多时，推荐先发布到 staging：

复制shorebird patch android --release-version 1.1.0+2 --track staging

然后用支持该通道的测试客户端或官方预览流程验证。只发布到 staging，不代表测试手机会自动切换通道。 如果应用在更新 SDK 调用中明确指定 UpdateTrack.stable，其应用内检查仍请求 stable；要先准备能请求 staging 的验证方式，不能把“没发现更新”当成补丁有问题。通道与设备订阅

验证完成后，把已经测过的补丁移动到 stable。先查看控制台记录，或者列出目标版本的补丁：

复制shorebird patches list --release-version 1.1.0+2

以下假设待推广的实际补丁编号为 2：

复制shorebird patches set-track --release-version 1.1.0+2 --patch-number 2 --track stable

此参数形式需要 Shorebird CLI 1.6.128 或更新版本。移动通道无需重新构建，因而正式发布的是刚才验收过的补丁。预发布与推广流程

#六、怎样证明用户真的更新成功

本文示例应用在启动后后台检查和下载，页面允许继续使用；也提供手动检查与重试。补丁就绪后，下一次完整启动才运行新代码。切到后台再返回，通常不等于应用进程重新启动。

一次实际验收可以这样做：

1. 安装目标基础包，登录测试账号，创建一条测试数据并记录外观偏好。
2. 在 Dart 中修改一处可识别的文案，发布补丁到待验收通道。
3. 在已安装应用中检查更新，确认下载完成并提示更新就绪。
4. 完全关闭并重新打开应用，确认新文案和当前补丁编号生效。
5. 检查登录态、测试数据和外观偏好仍然保留，核心业务可以继续使用。
6. 补测断网、下载失败后恢复网络重试，以及更新过程中继续编辑的行为。

记录基础版本、补丁编号、设备型号、系统版本和结果。自动测试证明代码行为，模拟器证明模拟器路径；真机触摸、网络变化和后台恢复需要对应设备证据。不要把“补丁上传成功”“显示下载完成”和“新代码已运行”合并成一个状态。

#七、发现问题如何回滚

先定位出问题的平台、基础版本和补丁编号。可以在 Shorebird 控制台选中对应补丁回滚，也可以使用 CLI：

复制shorebird patches rollback --release-version 1.1.0+2 --patch-number 2

确认命令对应正确的平台补丁，并查看回滚结果。设备要再次检查更新、处理回滚并重新启动后，才运行之前可用的代码；离线设备不会立刻改变。

回滚当前补丁会退到该通道仍可用的前一个补丁，没有可用补丁时退到基础版本。如果多个后续补丁都有问题，需要核对整个回退链。代码回滚也不会自动撤销数据库内容或服务端数据变化，因此涉及存储结构的修改要考虑旧代码兼容性。回滚行为

#八、保存一份发布记录

每次发布建议留下以下记录，便于复现和排查：