Flutter 动态化 SDK 接入指引

一、隐私安全说明

Flutter 动态化 SDK
版本：1.7.1
更新时间：2026年1月15日
SDK介绍：为Flutter开发框架提供动态化能力，方便开发者在线更新或修复问题
服务提供方：深圳市腾讯计算机系统有限公司
接入指引：Flutter 动态化 SDK 接入指引
隐私保护规则：《Conch 动态化 SDK 隐私保护规则》

二、获取 SDK 和 License

Flutter动态化属于限制开放功能，有兴趣的用户请联系我们，以获取SDK和相关使用权限。

三、SDK接入

Conch-Flutter SDK 通过改造 Dart 编译器，并配套自主研发的 Dart 解释器，构建了一套完整的运行时服务体系，实现了对 Flutter 应用的动态修复与热更新能力。

整体流程概览

Conch-Flutter SDK 的完整使用流程分为四个流程，从项目改造到补丁发布形成完整的闭环，如下图所示：

流程一：接入 SDK 并改造项目

完成 Conch-Flutter SDK 环境搭建，确保开发环境配置完整（详见 3.1 配置 Conch-Flutter SDK ）
在应用启动入口接入 runAppWrapper()，并调用补丁加载方法。（详见 3.2 项目改造）

流程二：编译基准包（详见四、编译基准包）

Android 端：执行 flutter build apk --release 编译基准包
iOS 端：执行 flutter build ios --release 编译基准包
生成两个重要产物：
- 安装包：APK（Android）或 IPA（iOS），用于应用分发和上线
- 符号文件（conch_base_<versionCode>.json）：记录当前版本所有方法及符号信息，必须归档保存，是后续制作补丁的关键依据

流程三：编译补丁（详见五、补丁制作）

在基准包发布后，当需要修复 Bug 或调整功能时：
- 准备基准包符号文件（从归档中获取）
- 执行 flutter build patch 制作补丁包

流程四：上传到平台（详见六、发布补丁）

将生成的补丁包上传到 Shiply 平台进行发布和管理
实现 Flutter 应用的热更新

3.1 配置 Conch-Flutter SDK

3.1.1 克隆 Conch-Flutter 仓库

克隆仓库命令：

git clone https://cnb.cool/tencent-tds/Conch-Flutter

认证信息：

第一次拉取时会要求输入认证信息，如图所示：

cnb_git

输入用户名和 Token：

Username：cnb
Password：输入我们提供的 Token 作为密码

切换到指定版本：

git checkout flutter3.22.3_extRelease1.7.1

版本 Tag 命名规则说明：

Tag 的命名格式为：flutter{Flutter版本号}_extRelease{Conch SDK版本号}

示例：flutter3.22.3_extRelease1.7.1
Flutter版本号：3.22.3（对应 Flutter 框架版本）
Conch SDK 版本号：1.7.1（对应 Conch 动态化 SDK 版本）

注意事项：

请确保使用与您项目 Flutter 版本匹配的 Tag 版本
如果项目路径包含中文、空格或特殊字符，请将项目移动到纯英文路径下，否则可能导致编译失败
如果遇到认证问题，请确认 Token 是否有效或联系技术支持

3.1.2 配置环境变量

将 Conch 定制的 Flutter SDK 路径加入环境变量（以 macOS 为例）：

export PATH=/{YourPath}/conch-flutter/bin:$PATH

替换 {YourPath} 为实际路径。

3.1.3 macOS 弹窗问题处理

macOS 上运行某些未经公证的应用或工具时，系统会弹出安全警告窗口（如“无法打开应用”或“来自身份不明的开发者”提示）。

Conch SDK 及其相关工具链经过合规检测，但由于某些二进制文件以及工具链的特殊性，运行时可能会触发系统的安全防护，导致弹窗提示。这是一种正常现象，不影响 Conch 的功能和开发使用。

macOS 会给从网络下载的应用或文件打上 com.apple.quarantine 属性（即 Quarantine），导致运行时弹窗。可以通过解除该属性来避免弹窗。我们在后续新发布的 SDK 包中都添加了相关的解除脚本，脚本执行过程中需要输入 sudo 密码，使用步骤如下：

cd /{YourPath}/conch-flutter
sh ./xattr_quarantine_inFlutter.sh

将会得到以下输出：

正在检测并解除 Flutter 工具 quarantine 属性...
flutter目录 {YourPath}/conch-flutter
已经解除flutter工具的quarantine属性,避免弹窗！

3.1.4 验证配置

执行以下命令，检查 Flutter SDK 是否配置成功：

flutter --version

输出类似如下内容，Flutter 版本输出Conch extReleasex.x.x 字样即为成功：

enheng@LUCKIERGONG-MC2 ~ % flutter --version
ConchFlutter execute: --version
Flutter 3.22.3 • Conch extRelease1.7.1 • channel [user-branch] • https://cnb.cool/tencent-tds/Conch-Flutter
Framework • revision aa73bc9e53 (11 days ago) • 2025-11-20 17:23:32 +0800
Engine • revision 27fce7e964
Tools • Dart 3.4.4 • DevTools 2.34.1

flutter doctor -v

输出类似如下内容，Flutter SDK 路径为刚配置的Conch Flutter路径即为成功：

ConchFlutter execute: doctor -v
[!] Flutter (Channel [user-branch], 3.22.3, on macOS 15.6 24G84 darwin-arm64 (Rosetta), locale zh-Hans-CN)
    ! Flutter version 3.22.3 on channel [user-branch] at /Users/enheng/development/conch-flutter-cnb
      Currently on an unknown channel. Run `flutter channel` to switch to an official channel.
      If that doesn't fix the issue, reinstall Flutter by following instructions at
      https://flutter.dev/docs/get-started/install.
    ! Upstream repository https://cnb.cool/tencent-tds/Conch-Flutter is not a standard remote.
      Set environment variable "FLUTTER_GIT_URL" to https://cnb.cool/tencent-tds/Conch-Flutter to dismiss this
      error.
    • Framework revision aa73bc9e53 (11 days ago), 2025-11-20 17:23:32 +0800
    • Engine revision 27fce7e964
    • Dart version 3.4.4
    • DevTools version 2.34.1
    • If those were intentional, you can disregard the above warnings; however it is recommended to use "git"
      directly to perform update checks and upgrades.

[✓] Android toolchain - develop for Android devices (Android SDK version 36.1.0)
    • Android SDK at /Users/enheng/Library/Android/sdk
    • Platform android-36, build-tools 36.1.0
    • Java binary at: /Users/enheng/Library/Java/JavaVirtualMachines/ms-17.0.16/Contents/Home/bin/java
    • Java version OpenJDK Runtime Environment Microsoft-11926164 (build 17.0.16+8-LTS)
    • All Android licenses accepted.

3.2 项目改造

3.2.1 配置 Conch 依赖

步骤 1：添加 Conch API 依赖

在 pubspec.yaml 文件的 dependencies 部分添加 Conch API 依赖：

dependencies:
  conch_api:
    sdk: flutter

步骤 2：配置 Conch 插件参数

在 pubspec.yaml 文件的顶层（不在 dependencies 内）添加 Conch 配置：

# Conch 动态化配置（文件顶层）
conch:
  enable: true                  # 是否开启 Conch 热更功能
  versionCode: 1.0.0            # 本次构建的版本号
  targetBaseVersions: 1.0.0     # 补丁制作时生效，指定目标基准版本
  licensePath: ./conch_license  # 授权证书文件路径

3.2.2 源码改造

只需修改应用启动入口文件（通常是 lib/main.dart），将 runApp() 替换为 runApp(ConchLoaderAPI.runAppWrapper())，并在 App 启动后适当时机调用 ConchLoaderAPI.requestPatch() 方法预下载最新补丁即可。

步骤 1：导入 Conch API

import 'package:conch_api/conch_api.dart';

步骤 2：配置运行参数

创建 ConchParams 对象，配置必要参数（参数详解见下文参数详解）：

final params = ConchParams(
  appId: "your_app_id",        // 必填：Shiply 平台分配的 AppId
  appKey: "your_app_key",      // 必填：Shiply 平台分配的 AppKey
  moduleName: "your_module",   // 必填：模块名称（与 Shiply 平台一致）
  appVersion: "1.0.0",         // 必填：应用版本号
  deviceId: "device_123",      // 可选：设备ID（用于灰度发布）
  env: "online"                // 可选：shiply发布环境标识，默认为`"online"`正式环境，其他环境为对应的环境ID。
);

步骤 3：替换启动方式

将原来的 runApp(const MyApp()) 替换为 runApp(ConchLoaderAPI.runAppWrapper())：

改造接入示例：

import 'package:flutter/material.dart';
import 'package:conch_api/conch_api.dart'; // ① 导入

void main() {
  //原始
  //runApp(const MyApp()); 

  final params = ConchParams(          // ② 配置参数
    appId: "your_app_id",              // 从 Shiply 获取
    appKey: "your_app_key",            // 从 Shiply 获取
    moduleName: "your_module",         // 模块名称
    appVersion: "1.0.0",               // 应用版本
  );

  runApp(                              // ③ 替换启动方式
    ConchLoaderAPI.runAppWrapper(
      params,
      appBuilder: () => const MyApp(),
    ),
  );
}

class MyApp extends StatelessWidget {
  const MyApp({super.key});
  @override
  Widget build(BuildContext context) {
    return MaterialApp(
      title: 'My App',
      home: Scaffold(
        body: Center(
          child: Text('Hello World'),
        ),
      ),
    );
  }
}

步骤 4：拉取最新补丁

重要： 必须在业务中手动调用 requestPatch() 拉取补丁，否则无法拉取远程补丁到本地。

// 在 App 启动后的合适时机调用
ConchLoaderAPI.requestPatch();

说明：

从服务器拉取补丁并安装到本地
仅下载和安装，不加载到运行时
下次冷启动时自动加载已下载的补丁

3.2.3 补丁状态查询

调用 queryPatchLoadResult() 可同步查询当前补丁加载状态，不触发网络请求或补丁加载。

final result = ConchLoaderAPI.queryPatchLoadResult();

返回值 PatchLoadResult?：

非 null：包含补丁加载状态（resultCode、moduleName、version、taskId）
null：加载流程未完成

详细的 API 介绍见 API 详细文档

四、编译基准包

完成 SDK 接入后，按以下流程制作基准包：

基准包流程图

操作步骤：

在 pubspec.yaml 中配置 versionCode（建议与 appVersion 保持一致，如 1.0.0）
执行编译命令：flutter build apk --release / flutter build ios --release
获取产物：
- 基准包 APK（用于发布）
- 符号文件 .dart_tool/conch_build/conch_base_1.0.0.json（必须归档保存）

重要提示：

符号文件是制作补丁的必要依据，每个基准包版本的符号文件都必须妥善保存。
Conch 只有在 release 模式下才会生效。

五、补丁制作

基准包发布后，在修复 Bug 或调整功能时，可基于基准包制作补丁：

补丁包流程图

操作步骤：

1. 准备符号文件

将归档的基准包符号文件（如 conch_base_1.0.0.json）放入项目根目录的 conch_base/ 目录下（不存在则需手动创建）。

2. 配置补丁参数

在 pubspec.yaml 中配置：

conch:
  enable: true
  versionCode: 1.0.0+1           # 补丁版本号（建议以基准包版本递增1.0.0+n）
  targetBaseVersions: 1.0.0      # 目标基准包版本（必须与符号文件版本一致）

参数说明：

targetBaseVersions：必须与符号文件版本完全匹配（如符号文件为 conch_base_1.0.0.json，则填 1.0.0），否则因找不到对应的基准符号文件而编译失败
versionCode：补丁符号文件版本号，建议递增（如 1.0.0+1、1.0.0+2）

3. 编译补丁

flutter build patch

编译完成后，会生成以下产物：

补丁包：.dart_tool/conch_build/patch_zip/conch_result_diff.zip（需要上传到 Shiply 平台）
补丁符号文件：.dart_tool/conch_build/conch_base_1.0.0+1.json（可忽略，无需保存）

说明： 补丁符号文件可以忽略。

六、发布补丁

将生成的补丁包 conch_result_diff.zip 上传到 Shiply 发布平台进行发布。

发布平台使用详见：《平台使用指引》

七、常见问题及解决方案

文档参考：查阅 FAQ 文档获取常见问题解答

Flutter 动态化 SDK 接入指引

一、隐私安全说明​

二、获取 SDK 和 License​

三、SDK接入​

3.1 配置 Conch-Flutter SDK​

3.1.1 克隆 Conch-Flutter 仓库​

3.1.2 配置环境变量​

3.1.3 macOS 弹窗问题处理​

3.1.4 验证配置​

3.2 项目改造​

3.2.1 配置 Conch 依赖​

3.2.2 源码改造​

3.2.3 补丁状态查询​

四、编译基准包​

五、补丁制作​

六、发布补丁​

七、常见问题及解决方案​