从零开始掌握 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 方案

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

📱 平台支持现状

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

五、总结与最佳实践

核心命令速查

bash 复制代码

# 生命周期命令
shorebird init          # 初始化
shorebird release       # 发布版本（基础包）
shorebird patch         # 发布补丁（热更新）

适用场景建议

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

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