从零开始掌握 Shorebird:Flutter 热更新实战指南

从零开始掌握 Shorebird:Flutter 热更新实战指南

在 Flutter 开发中,热更新一直是个让人又爱又恨的难题。Shorebird 的出现,很好地解决了这个痛点。本文将从环境搭建到生产实践,手把手带你掌握 Shorebird 的核心用法,并特别针对国内开发者关心的网络和平台问题给出实用建议。

一、Shorebird 是什么?

Shorebird 是一个为 Flutter 提供代码推送服务的平台,由 Flutter 创始团队成员创立,被公认为最接近官方的热更新方案。

核心优势:

  • ✅ 性能无损:Android 端保持 AOT 运行,iOS 端修改代码通过解释器执行(性能保留 90% 以上)
  • ✅ 平台合规:技术绕过应用商店限制,符合 Google Play 和 App Store 政策
  • ✅ 低侵入性:日常开发仍用标准 Flutter 命令,仅在发布时使用 Shorebird CLI

二、三步上手 Shorebird

🛠️ 第一步:环境配置与项目初始化

在开始前,请确保你的网络可以稳定访问海外服务(Shorebird CLI 和默认服务托管在海外)。

1. 安装 Shorebird CLI

bash 复制代码
curl --proto '=https' --tlsv1.2 https://raw.githubusercontent.com/shorebirdtech/install/main/install.sh -sSf | bash

安装后运行验证:

bash 复制代码
shorebird doctor

2. 登录账号

bash 复制代码
shorebird login

浏览器会自动打开授权页面,使用 Google 或 Microsoft 账号登录即可。

3. 初始化项目 进入 Flutter 项目根目录:

bash 复制代码
shorebird init

这个命令会自动完成:

  • 创建 shorebird.yaml 配置文件(含唯一 app_id)
  • 添加 shorebird_code_push 依赖
  • 配置 Android 网络权限和 .gitignore
  • 在 Shorebird 控制台创建应用记录

💡 国内网络小贴士:如果登录或安装缓慢,可以尝试为终端配置代理,或复制链接在代理模式下手动访问。

📦 第二步:发布第一个版本

在发布补丁前,需要先发布一个通过 Shorebird 构建的"基础版本"。

Android 版本发布

bash 复制代码
# 生成 AAB(默认,用于 Google Play)
shorebird release android

# 如需生成 APK
shorebird release android --artifact apk

iOS 版本发布

bash 复制代码
shorebird release ios

⚠️ 注意:发布 iOS 版本前,请确保已在 Xcode 中完成证书和配置文件设置。

执行成功后,Shorebird 会上传符号文件到服务器,生成的安装包(AAB/IPA)即可上传至应用商店。

🩹 第三步:发布热更新补丁

应用上线后,假设需要修复一个小 Bug:

1. 修改 Dart 代码(如修复逻辑或调整 UI)

2. 发布补丁

bash 复制代码
# Android 补丁
shorebird patch android

# iOS 补丁
shorebird patch ios

Shorebird 会自动对比新旧代码,生成极小(通常几十到几百 KB)的二进制补丁包并上传。

更新生效机制:

  • 用户首次打开 App → 后台静默下载补丁
  • 用户第二次打开 App → 更新自动生效(不中断当前会话)

三、进阶技巧:精细化控制

通过 shorebird_code_push 包提供的 API,可以实现更灵活的控制:

手动检查更新

dart 复制代码
import 'package:shorebird_code_push/shorebird_code_push.dart';

final _shorebirdCodePush = ShorebirdCodePush();

void checkForUpdate() async {
  // 1. 检查是否有可下载更新
  final isUpdateAvailable = await _shorebirdCodePush.isNewPatchAvailableForDownload();
  if (isUpdateAvailable) {
    // 2. 下载更新
    await _shorebirdCodePush.downloadUpdateIfAvailable();
  }
}

void applyUpdate() async {
  // 3. 在合适时机(如点击"重启应用"按钮)安装更新并重启
  if (await _shorebirdCodePush.isNewPatchReadyToInstall()) {
    await _shorebirdCodePush.installUpdateAndRestart();
  }
}

结合 CI/CD 自动化

Shorebird 可以无缝集成到 Codemagic 等 CI/CD 工具中,实现版本发布和补丁更新的全自动化流程。

四、重要注意事项

📌 更新范围限制

Shorebird 补丁只能更新 Dart 代码,以下变更必须通过新的应用商店版本发布:

  • ❌ 原生代码修改(android/ 或 ios/ 目录)
  • ❌ pubspec.yaml 依赖变更
  • ❌ 新增资源文件(图片、字体等)

🌐 国内生产环境优化

Shorebird 默认服务在海外,国内使用时建议:

自定义 CDN 方案

  1. 将补丁包托管到国内云存储(如阿里云 OSS、七牛云)
  2. 修改客户端代码,从你的 CDN 地址下载补丁
  3. 大幅提升用户下载速度和成功率

📱 平台支持现状

平台 支持情况 说明
Android ✅ 完美支持 性能无损,完全合规
iOS ✅ 完美支持 遵守 App Store 规则
鸿蒙 (HarmonyOS NEXT) ❌ 不支持 官方暂无计划,需关注后续动态

五、总结与最佳实践

核心命令速查

bash 复制代码
# 生命周期命令
shorebird init          # 初始化
shorebird release       # 发布版本(基础包)
shorebird patch         # 发布补丁(热更新)

适用场景建议

  • ✅ 推荐使用:仅覆盖 Android + iOS 的中大型 App,追求高性能和低接入成本
  • ⚠️ 暂不适用:必须覆盖鸿蒙系统的项目(需等待官方支持)
  • 💪 最佳实践:国内生产环境务必配置自定义 CDN,确保补丁下载体验

Shorebird 以其优秀的性能和合规性,已成为 Flutter 热更新的首选方案。通过本文的指引,相信你已经能够顺利上手。如果在实际操作中遇到问题,欢迎随时交流探讨。

相关推荐
好的佩奇4 小时前
蓝牙之设备角色与连接
android·flutter·蓝牙
SoaringHeart1 天前
Flutter最佳实践:用 flutter_html 渲染富文本
前端·flutter
恋猫de小郭2 天前
Flutter 3.50.0 Release 的第一个崩溃,修好了,还没 hotfix
android·前端·flutter
程序员老刘2 天前
跨平台开发地图 | 2026年11月
flutter·ai编程·客户端
传奇开心果编程3 天前
【Flutter踩坑排雷】第30课:异常未捕获坑|未捕获异常直接闪退,全局兜底故障处理
android·flutter·ios·移动开发·dart·ui框架·声明式ui
恋猫de小郭3 天前
Flutter Native Interop 稳定了,Platform Channel 要退场了
android·前端·flutter
好的佩奇3 天前
Dart 之可迭代对象与生成器
android·flutter·dart
恋猫de小郭4 天前
Flutter Analyzer 系列坑推进,必看,AI 时代这玩意最吃你内存
android·前端·flutter
LinXunFeng4 天前
拿竞品 App 一扫,技术栈全暴露了
android·flutter·开源
传奇开心果编程5 天前
【Flutter踩坑排雷】第28课:平台目录缺失与修复坑|`flutter create` 的“重建”与“覆盖”边界
android·flutter·ios·移动开发·跨平台·dart·声明式ui