Shiply Flutter 动态化常见使用问题

常见问题

1. Exception: AOT snapshotter exited with code -9

此错误通常由以下两种原因导致：

1.1 macOS 安全限制

问题描述：macOS 系统阻止了 Flutter 引擎执行。

解决方案：运行 SDK 包中的处理脚本，参照 SDK 接入指引中的 "macOS 弹窗问题处理方法"，运行 SDK 包中的 xattr_quarantine_inFlutter.sh 脚本即可解决。

1.2 Android 堆内存不足

问题描述：在构建大型项目或资源密集型操作时出现内存不足。

解决方案：修改 android/gradle.properties 文件，增加堆内存设置：

org.gradle.jvmargs=-Xmx8192M

2. Conch-Flutter未生效

当项目配置文件中 enable: true 同时使用 release 模式编译时，Conch 才会生效。

未生效时常见日志样式：

[ConchLoaderAPI] ConchLoader#load() conch 仅在 release build 模式下生效 (当前为 debug 模式)
[ConchLoaderAPI] ConchLoader#init() conch 仅在 release build 模式下生效 (当前为 debug 模式)

问题排查：如果没有输出 ConchLoader 的详细日志，说明 Conch 没有生效。此时需要：

尝试清理缓存
检查配置是否正确
确认编译是否为 release 模式
检查工程路径是否存在中文，要求英文路径

3. ConchCoreAPI.enableDebugLog() Debug 开关

开启 Debug 模式后，将会输出详细的 Conch 日志，便于问题定位和调试。

注意：开启Debug模式后，App性能将受到影响，在产品上线时谨记关闭Debug开关。

4. 图片资源热更新未生效

Conch 支持对 App 内的图片资源进行热更新，此功能独立于代码热更新。其原理是通过自定义的 conchBundle，优先从本地的热更新补丁文件中加载图片资源。

4.1 自动更新（无需额外配置）

如果您的应用直接使用 Flutter 官方提供的 Image.asset、SvgPicture.asset、AssetImage 来加载图片，那么 Conch 在应用补丁后会自动处理这些加载请求。

只需在对应的函数上打上 @PatchOnly 注解并制作相应补丁，即可实现图片热更新。Conch 会优先从更新后的补丁文件中加载新图片。

4.2 手动配置（用于自定义图片加载方式）

对于非标准的或自定义的图片资源加载方式，Conch 无法自动识别。为了让热更新对这些图片生效，您需要手动将应用的默认 AssetBundle 替换为 Conch 提供的 conchBundle。

使用方法：在 widget 树最外层套一层 DefaultAssetBundle，使所有资源加载都默认使用此 bundle：

DefaultAssetBundle(
  bundle: conchBundle,
  child: Widget(),
);

进阶使用

1. 对通过 dependencies 引入的 package 内容进行热更新

在 Conch 热更新机制中，默认情况下热修主要针对主工程代码。当业务逻辑需要对通过 dependencies 引入的 package 内容进行热更新时，需要借助 moduleIncludes 和 hotfixModuleIncludes 这两个配置项来扩大热更新的有效范围。

1.1 moduleIncludes

moduleIncludes 用于定义多模块的业务范围，并将其全面纳入热更新的有效范围。在此配置的模块将具备以下特性：

函数热修范围：配置的模块内的函数支持独立热修
API保留：在基准包构建时，此范围内调用的 API 都将被保留，确保热更新后的兼容性
页面热更扩散范围：进行页面热更新时，补丁会自动扩散到此配置的模块，确保热更新的业务代码最新且完整

使用场景：适用于多模块业务场景，当需要将主工程之外的 dependencies 包也纳入页面热更新的自动扩散范围时使用。

conch:
  moduleIncludes: 
    - package:xxx
    - package:xxx

1.2 hotfixModuleIncludes

hotfixModuleIncludes 也用于定义多模块的业务范围，但其在页面热更新的扩散行为上有所限制。在此配置的模块将具备以下特性：

函数热修范围：配置的模块内的函数支持独立热修
API保留：在基准包构建时，此范围内调用的 API 都将被保留，确保热更新后的兼容性
页面热更扩散限制：进行页面热更新时，补丁不会自动扩散到此配置的模块（这是与 moduleIncludes 的主要区别）

使用场景：

希望支持对该模块内的函数进行独立热修
不希望在页面热更新时，补丁自动扩散到该模块，以避免不必要的更新、潜在的冲突或出于性能考虑
适用于某些大型或不常变动的模块，仅需支持函数级别的热修，而无需整体页面热更时被动更新

conch:
  hotfixModuleIncludes: 
    - package:xxx
    - package:xxx

重要注意事项：

业务范围默认已包含主工程，无需在此重复配置主工程
此配置项需要在构建基准包时进行配置，以确保基准包中包含这些模块的元数据和 API 保留信息

Shiply Flutter 动态化常见使用问题

常见问题​

1. Exception: AOT snapshotter exited with code -9​

1.1 macOS 安全限制​

1.2 Android 堆内存不足​

2. Conch-Flutter未生效​

3. ConchCoreAPI.enableDebugLog() Debug 开关​

4. 图片资源热更新未生效​

4.1 自动更新（无需额外配置）​

4.2 手动配置（用于自定义图片加载方式）​

进阶使用​

1. 对通过 dependencies 引入的 package 内容进行热更新​

1.1 moduleIncludes​

1.2 hotfixModuleIncludes​