基于 FlutterPatch 快速接入 Flutter 热更新

官网:flutterpatch.cn

客户端封装包:flutterpatch(代码热更 + 资源热更,一套 API)


一、部署服务

  1. 打开官网,点「立即接入」,拿到授权 ID
  2. 在服务器执行:
bash 复制代码
curl -fsSL https://flutterpatch.cn/install_remote.sh | bash -s -- \
  --version <版本号> \
  --license <授权ID>

装完会得到:

  • API 地址(如 https://ota.你的域名)
  • Dashboard 后台
  • Token(给 CLI 用)

二、接入热更新

Demo 工程:可以用Flutter 随便创建一个Demo

1. 加依赖

不要直接依赖 shorebird_code_push,改用封装包 flutterpatch(内部已包含代码推送,并支持资源热更新):

yaml 复制代码
dependencies:
  flutterpatch: ^0.1.5
bash 复制代码
flutter pub get

2. 配 shorebird.yaml

yaml 复制代码
app_id: <控制面里的 app_id>
base_url: https://ota.你的域名   # 指向已部署的服务
auto_update: false              # 必须关闭,见下方说明

务必关闭 auto_update。

为 true 时 Shorebird 引擎会在启动时自己检查并下载补丁,绕过 FlutterPatch.sync() 里写的白名单 / uniqueId 过滤。关闭后只由业务调用 sync() 决定是否下载。

并在 pubspec.yaml 里声明为 asset:

yaml 复制代码
flutter:
  assets:
    - shorebird.yaml

3. 初始化(替换原来的 Shorebird 调用)

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

Future<void> main() async {
  WidgetsFlutterBinding.ensureInitialized();

  runApp(
    await FlutterPatch.bootstrap(
      const MyApp(),
      appPackage: 'sample_app', // 与工程包名/资源包约定一致
    ),
  );
}

// 有网络、登录拿到用户 id 后再同步(代码补丁 + 资源包)
// bootstrap 不上网;必须先 setUniqueId,再 sync,过滤才生效
Future<void> onReady() async {
  FlutterPatch.setUniqueId(userId); // 白名单灰度:通常为业务 uid
  final result = await FlutterPatch.sync();
  // result 里可看代码是否 outdated、资源是否更新
}

sync() 一次完成(且会走客户端白名单逻辑):

  • 代码热更 :check → uniqueId 命中才下载 Dart 补丁(下次冷启动生效)
  • 资源热更:拉取资源包,图片等可较快生效
  • 未命中白名单时不会 再走 Shorebird update()

4. 资源怎么用(支持热更)

保持 Image.asset 可用;更推荐走封装 API,音频/视频等也统一:

dart 复制代码
// 图片
FlutterPatch.image('assets/images/banner.png', width: 200);

// 字节 / 文件(音频、视频等)
final bytes = await FlutterPatch.loadBytes('assets/audios/click.mp3');
final file = await FlutterPatch.file('assets/videos/intro.mp4');

说明:

  • 只能替换安装包里已有的 asset key,不要靠热更「新增全新路径」
  • 不要热更 fonts/(启动时由 pubspec 注册)
  • 资源包的 release_version 要和当前安装版本对齐

5. 发版与打补丁

bash 复制代码
# 安装 CLI(官网下载页)
./install_cli.sh
export FLUTTERPATCH_TOKEN=<token>

# Android 发版并安装
flutterpatch release android --upload-baselines
adb install -r build/app/outputs/flutter-apk/app-release.apk

# iOS 发版(必须真机;模拟器不支持 patch)
flutterpatch release ios --upload-baselines
# 用 Xcode / TestFlight 安装到真机

改业务代码或资源后:

bash 复制代码
# 发前可检查能否 OTA
flutterpatch check-ota --version 1.0.0+1

# Android 打补丁
flutterpatch patch --platforms=android --release-version=1.0.0+1

# iOS 打补丁
flutterpatch patch --platforms=ios --release-version=1.0.0+1

# 双端一起打
flutterpatch patch --platforms=android,ios --release-version=1.0.0+1

验证代码热更:

  1. Demo 改 代码
  2. patch 上传
  3. App 里 FlutterPatch.sync() 下载成功
  4. 完全退出再打开 → 查看最新运行结果

验证资源热更:换一张已有路径的图,发资源包 → sync → UI 显示新图(一般无需等代码冷启动)。

必须用 flutterpatch release 打的包安装;普通 flutter run 没有代码热更能力。

iOS 热更只能在真机验证,模拟器无效。

相关推荐
程序员老刘12 小时前
跨平台开发地图 | 2026年11月
flutter·ai编程·客户端
传奇开心果编程18 小时前
【Flutter踩坑排雷】第30课:异常未捕获坑|未捕获异常直接闪退,全局兜底故障处理
android·flutter·ios·移动开发·dart·ui框架·声明式ui
恋猫de小郭19 小时前
Flutter Native Interop 稳定了,Platform Channel 要退场了
android·前端·flutter
好的佩奇1 天前
Dart 之可迭代对象与生成器
android·flutter·dart
恋猫de小郭2 天前
Flutter Analyzer 系列坑推进,必看,AI 时代这玩意最吃你内存
android·前端·flutter
LinXunFeng2 天前
拿竞品 App 一扫,技术栈全暴露了
android·flutter·开源
传奇开心果编程3 天前
【Flutter踩坑排雷】第28课:平台目录缺失与修复坑|`flutter create` 的“重建”与“覆盖”边界
android·flutter·ios·移动开发·跨平台·dart·声明式ui
程序员老刘·4 天前
Flutter 3.50更新,开发者应该关注什么?
flutter·ai编程·跨平台开发
传奇开心果编程4 天前
【Flutter踩坑排雷】第25课:ScrollController 误用坑|跳转失效、监听泄漏与“控制器未附加”
android·flutter·ios·移动开发·跨平台·dart·声明式ui
程序员老刘4 天前
Flutter 3.50更新,开发者应该关注什么?
flutter·ai编程·客户端