Flutter 客户端热更新实战

掘金前端

作者前端荣耀

2026年3月17日 20:03

本文将带你深入了解 Flutter 热更新的实现原理，并手把手教你使用 Shorebird 实现生产环境的热更新能力。

为什么需要热更新？

作为 Flutter 开发者，你是否遇到过这样的场景：

刚上线的版本发现了一个紧急 Bug，但应用商店审核需要 2-5 天
想快速验证一个小功能的效果，不想等待漫长的审核周期
需要在不发布新版本的情况下修复线上问题

传统应用发布流程：代码修改 → 构建 → 提交审核 → 等待审核 → 发布 → 用户更新，整个过程可能需要数天甚至数周。

而热更新可以将这个周期缩短到 几分钟：代码修改 → 推送补丁 → 用户下次启动生效。

Flutter 热更新的技术挑战

Flutter 采用 AOT（Ahead-Of-Time）编译，代码在发布时已经编译为机器码。这与 React Native 的 JS Bundle 模式不同，Flutter 无法直接像 RN 那样替换代码包。

但 Flutter 官方团队核心成员创立的 Shorebird 项目，通过巧妙的技术方案解决了这个问题：

Android：直接替换 Dart VM 中的编译代码，性能几乎无影响
iOS：使用自定义 Dart 解释器 + 智能链接器，仅对修改部分使用解释执行，约 98% 的代码仍以 AOT 模式全速运行

更重要的是，Shorebird 完全符合 Google Play 和 Apple App Store 的政策要求。

Shorebird 快速上手

第一步：安装 CLI 工具

# macOS / Linux
curl --proto '=https' --tlsv1.2 https://raw.githubusercontent.com/shorebirdtech/install/main/install.sh -sSf | bash

# 验证安装
shorebird --version

安装完成后，运行诊断命令确保环境正常：

shorebird doctor

第二步：注册账号并登录

访问 console.shorebird.dev 注册账号
在终端登录：

shorebird login

这将打开浏览器完成认证，成功后会显示登录信息。

第三步：初始化项目

对于现有 Flutter 项目，只需执行：

cd your_flutter_project
shorebird init

这会在项目根目录生成 shorebird.yaml 配置文件：

# shorebird.yaml
app_id: ee322dc4-3dc2-4324-90a9-04c40a62ae76
# auto_update: false  # 取消注释可禁用自动更新

注意：app_id 可以公开，不是敏感信息。

第四步：创建 Release

在推送热更新之前，必须先创建一个基准版本：

# Android
shorebird release android

# iOS（需要 macOS）
shorebird release ios

命令执行后会看到类似输出：

✓ Building release (17.0s)
✓ Fetching apps (0.3s)
✓ Detecting release version (0.2s)

🚀 Ready to create a new release!

📱 App: my_app (51751336-6a7c-4972-b4ec-8fc1591fb2b3)
📦 Release Version: 1.0.0+1
🕹️ Platform: android (arm64, arm32, x86_64)

Would you like to continue? (y/N) Yes
✓ Published Release!

生成的文件位置：

Android: ./build/app/outputs/bundle/release/app-release.aab
iOS: ./build/ios/ipa/<app_name>.ipa

第五步：上传到应用商店

Android (Google Play) ：将生成的 .aab 文件上传到 Google Play Console。

iOS (App Store) ：

推荐使用以下方式之一上传：

# 方式一：使用 Transporter（推荐）
# 在 App Store 下载 Transporter 应用，然后拖入 .ipa 文件

# 方式二：使用 xcrun notarytool（命令行）
xcrun notarytool submit build/ios/ipa/app.ipa \
  --apple-id YOUR_APPLE_ID \
  --password YOUR_APP_SPECIFIC_PASSWORD \
  --team-id YOUR_TEAM_ID

# 方式三：使用 Xcode
# 打开 Xcode → Window → Organizer → 选择归档 → Distribute App

iOS 重要提示：在 Xcode 分发时，必须取消勾选 "Manage Version and Build Number"，否则会影响补丁功能。

第六步：推送热更新补丁

当发现 Bug 或需要更新时：

# 修改 Dart 代码后，推送补丁
shorebird patch android

# 推送到指定通道
shorebird patch android --track=staging

输出示例：

✓ Building patch (17.2s)
✓ Fetching apps (0.7s)
✓ Detecting release version (0.2s)

🚀 Ready to publish a new patch!

📱 App: my_app (...)
📦 Release Version: 1.0.0+1
📺 Channel: stable
🕹️ Platform: android [arm64 (135 B), arm32 (150 B), x86_64 (135 B)]

Would you like to continue? (y/N) Yes
✅ Published Patch!

恭喜！你的第一个热更新补丁已经推送成功。用户下次启动应用时会自动下载并应用更新。

进阶：手动控制更新流程

默认情况下，Shorebird 会在应用启动时自动检查并下载更新。但有时你需要更精细的控制，比如：

显示更新进度
用户确认后再应用更新
指定更新通道进行灰度测试

添加依赖

# pubspec.yaml
dependencies:
  shorebird_code_push: ^2.0.5

代码实现

import 'package:shorebird_code_push/shorebird_code_push.dart';

class MyApp extends StatefulWidget {
  @override
  State<MyApp> createState() => _MyAppState();
}

class _MyAppState extends State<MyApp> {
  final updater = ShorebirdUpdater();

  @override
  void initState() {
    super.initState();
    _checkCurrentPatch();
  }

  Future<void> _checkCurrentPatch() async {
    final patch = await updater.readCurrentPatch();
    print('当前补丁版本: ${patch?.number}');
  }

  /// 手动检查并安装更新
  Future<void> checkForUpdates() async {
    try {
      final status = await updater.checkForUpdate();
      
      if (status == UpdateStatus.outdated) {
        // 有新版本可用
        final shouldUpdate = await _showUpdateDialog();
        if (shouldUpdate) {
          await updater.update();
          _showSuccessDialog('更新成功，下次启动生效');
        }
      } else if (status == UpdateStatus.current) {
        _showInfoDialog('已是最新版本');
      }
    } on UpdateException catch (e) {
      _showErrorDialog('更新失败: $e');
    }
  }

  Future<bool> _showUpdateDialog() async {
    return await showDialog<bool>(
      context: context,
      builder: (context) => AlertDialog(
        title: Text('发现新版本'),
        content: Text('检测到有新的更新，是否立即下载？'),
        actions: [
          TextButton(
            child: Text('稍后'),
            onPressed: () => Navigator.pop(context, false),
          ),
          ElevatedButton(
            child: Text('立即更新'),
            onPressed: () => Navigator.pop(context, true),
          ),
        ],
      ),
    ) ?? false;
  }

  @override
  Widget build(BuildContext context) {
    return MaterialApp(
      home: Scaffold(
        appBar: AppBar(title: Text('热更新示例')),
        body: Center(
          child: Column(
            mainAxisAlignment: MainAxisAlignment.center,
            children: [
              ElevatedButton(
                onPressed: checkForUpdates,
                child: Text('检查更新'),
              ),
            ],
          ),
        ),
      ),
    );
  }
}

禁用自动更新

如果希望完全手动控制更新时机，在 shorebird.yaml 中禁用自动更新：

# shorebird.yaml
app_id: your-app-id
auto_update: false

灰度发布与测试

使用多通道进行灰度发布

Shorebird 支持多个发布通道，非常适合灰度测试：

# 创建测试通道补丁
shorebird patch android --track=beta

# 创建预发布通道补丁
shorebird patch android --track=staging

# 创建生产通道补丁（默认）
shorebird patch android --track=stable

代码中指定通道

// 使用预定义的 beta 通道（推荐）
final status = await updater.checkForUpdate(track: UpdateTrack.beta);
if (status == UpdateStatus.outdated) {
  await updater.update(track: UpdateTrack.beta);
}

// 或使用自定义通道名称
const customTrack = UpdateTrack('my-custom-track');
final status = await updater.checkForUpdate(track: customTrack);
if (status == UpdateStatus.outdated) {
  await updater.update(track: customTrack);
}

完整的灰度发布流程

# 1. 推送测试版本到 beta 通道
shorebird patch android --track=beta

# 2. 本地预览（可选）
shorebird preview --track beta --app-id YOUR_APP_ID --release-version 1.0.0+1

# 3. 测试通过后，提升到 stable 通道
# 方式一：在控制台操作 https://console.shorebird.dev
# 方式二：重新推送到 stable 通道
shorebird patch android --track=stable

CI/CD 集成

在自动化构建流程中集成 Shorebird，实现一键发布：

生成 CI Token

shorebird login:ci

输出：

A token was generated.

SHOREBIRD_TOKEN="eyJhbGciOiJSUzI1NiIsImtpZCI6IjEifQ..."

You can use this token in CI environments by setting the SHOREBIRD_TOKEN environment variable.

GitHub Actions 配置

# .github/workflows/release.yml
name: Release with Shorebird

on:
  push:
    tags:
      - 'v*'

jobs:
  release:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      
      - name: Setup Java
        uses: actions/setup-java@v4
        with:
          distribution: 'temurin'
          java-version: '17'
      
      - name: Setup Flutter
        uses: subosito/flutter-action@v2
        with:
          flutter-version: '3.16.0'
      
      - name: Setup Shorebird
        uses: shorebirdtech/setup-shorebird@v1
        
      - name: Get dependencies
        run: flutter pub get
        
      - name: Release Android
        env:
          SHOREBIRD_TOKEN: ${{ secrets.SHOREBIRD_TOKEN }}
        run: |
          shorebird release android --force
          
      - name: Upload to Play Store
        uses: r0adkll/upload-google-play@v1
        with:
          serviceAccountJsonPlainText: ${{ secrets.PLAY_STORE_SERVICE_ACCOUNT }}
          packageName: com.example.app
          releaseFiles: build/app/outputs/bundle/release/app-release.aab
          track: internal

  patch:
    runs-on: ubuntu-latest
    needs: release
    if: github.event_name == 'push' && contains(github.ref, 'patch')
    steps:
      - uses: actions/checkout@v4
      
      - name: Setup Shorebird
        uses: shorebirdtech/setup-shorebird@v1
        
      - name: Push Patch
        env:
          SHOREBIRD_TOKEN: ${{ secrets.SHOREBIRD_TOKEN }}
        run: |
          shorebird patch android --force

常见问题与解决方案

Q1: 补丁推送后用户没有收到更新？

排查步骤：

# 1. 确认补丁已发布到正确通道
shorebird patches list

# 2. 检查应用版本号是否匹配
# 补丁只能应用于相同的 release 版本

# 3. 确认补丁发布到了 stable 通道（默认）
# 如果推送到 beta/staging，需要手动指定通道

注意：补丁在应用第二次启动时才会生效，这是设计如此。

Q2: iOS 补丁体积为什么比 Android 大很多？

这是正常现象：

平台	补丁大小	原因
Android	通常 KB 级别	直接替换编译代码
iOS	通常几百 KB	使用解释器模式，包含额外元数据

iOS 由于 App Store 政策限制，必须使用解释器执行更新代码，因此补丁体积较大。

Q3: 构建失败怎么办？

# 1. 检查环境
shorebird doctor

# 2. 清理缓存
shorebird cache clear

# 3. 重置 Shorebird 配置
rm -rf .shorebird
shorebird init

# 4. 检查 Flutter 版本
# Shorebird 需要使用其提供的 Flutter 版本
flutter --version

Q4: 哪些场景不能使用热更新？

场景	能否热更新	说明
修改 Dart 代码	✅ 支持	最常见的使用场景
修改 UI 布局	✅ 支持	纯 Dart 实现
修改业务逻辑	✅ 支持	纯 Dart 实现
修改原生代码（Java/Kotlin/Swift/ObjC）	❌ 不支持	需要发布新版本
新增权限	❌ 不支持	需要商店审核
更新原生依赖版本	❌ 不支持	需要发布新版本
改变应用主要功能	❌ 违规	违反商店政策

Q5: 如何追踪补丁版本用于数据分析？

void trackPatchVersion() async {
  final patchNumber = await ShorebirdUpdater().readCurrentPatch();
  
  // 上报到分析平台
  analytics.logEvent('app_launch', {
    'app_version': '1.0.0',
    'patch_number': patchNumber?.number ?? 0,
  });
}

Q6: 补丁会改变应用版本号吗？

不会。补丁是在相同版本号下的更新，不会修改 pubspec.yaml 中的版本号。

这可能导致分析平台无法区分热更新，建议通过补丁号进行追踪（见上一条）。

最佳实践

1. 合理规划版本发布策略

┌─────────────────────────────────────────────────────────────┐
│                   推荐发布策略                                │
├─────────────────────────────────────────────────────────────┤
│                                                             │
│  Release (商店版本)：                                        │
│  - 主要功能更新                                              │
│  - 原生代码变更                                              │
│  - 频率：每 2-4 周                                           │
│                                                             │
│  Patch (热更新)：                                            │
│  - 紧急 Bug 修复                                             │
│  - UI/文案调整                                               │
│  - 业务逻辑优化                                              │
│  - 频率：按需，随时推送                                       │
│                                                             │
└─────────────────────────────────────────────────────────────┘

2. 使用语义化版本号

# pubspec.yaml
version: 1.0.0+1

# 版本格式：major.minor.patch+buildNumber
# - major: 重大功能变更
# - minor: 功能迭代
# - patch: Bug 修复
# - buildNumber: 构建号（每次构建递增）

3. 建立 Staging 测试流程

# 开发 → Staging 测试 → 生产发布

# 1. 推送到 staging
shorebird patch android --track=staging

# 2. 测试人员验证
shorebird preview --track staging

# 3. 验证通过后提升到 stable
# 在控制台操作或使用命令

4. 为用户提供清晰的更新提示

// ✅ 好的做法
class UpdatePrompt {
  void showUpdateNotice(String version) {
    showDialog(
      context: context,
      builder: (context) => AlertDialog(
        title: Text('发现新版本'),
        content: Column(
          mainAxisSize: MainAxisSize.min,
          crossAxisAlignment: CrossAxisAlignment.start,
          children: [
            Text('版本 $version 包含以下更新：'),
            SizedBox(height: 8),
            Text('• 修复了登录页闪退问题'),
            Text('• 优化了首页加载速度'),
            Text('• 更新了用户协议'),
          ],
        ),
        actions: [
          TextButton(
            child: Text('稍后'),
            onPressed: () => Navigator.pop(context),
          ),
          ElevatedButton(
            child: Text('立即更新'),
            onPressed: applyUpdate,
          ),
        ],
      ),
    );
  }
}

// ❌ 不好的做法：静默更新且不告知用户
// 这可能导致用户困惑，且违反某些地区的用户知情权法规

定价与方案选择

Shorebird 提供灵活的定价方案，适合不同规模的团队：

计划	月费	月安装量	适用场景
Free	$0	5,000	个人项目、小型 MVP
Pro	$20	50,000	中小型应用
Business	$400	1,000,000	大型应用、企业项目
Enterprise	定制	定制	特殊需求

对于大多数中小团队，Pro 计划 已足够使用。如果月安装量超出配额，按 $1/2,500 次计算超额费用。

总结

Shorebird 为 Flutter 开发者提供了成熟、合规、易用的热更新解决方案。通过本文的实战指南，你应该已经掌握了：

核心原理：理解 Shorebird 如何在 Android/iOS 上实现代码热更新
基础使用：从安装到推送第一个补丁的完整流程
进阶控制：手动管理更新、灰度发布、多通道测试
CI/CD 集成：自动化构建发布流程
故障排查：常见问题的解决方案

热更新是一把双刃剑，合理使用可以大幅提升迭代效率，但也要注意：

不能滥用热更新绕过商店审核
遵守平台政策，不改变应用主要功能
做好版本追踪和数据分析

普通视图