基于 FlutterPatch 快速接入 Flutter 热更新

客户端封装包：flutterpatch（代码热更 + 资源热更，一套 API）

一、部署服务

打开官网，点「立即接入」，拿到授权 ID
在服务器执行：

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

验证代码热更：

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

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

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

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