MMKV 版本演进与技术路线图：从 v1.0.10 到 v2.4.2 的关键特性、破坏性变更与升级指南-平芜编程栈

KV存储
缓存
移动开发
存储

【免费下载链接】MMKV

An efficient, small mobile key-value storage framework developed by WeChat. Works on Android, iOS, macOS, Windows, POSIX, and OHOS.

项目地址：https://gitcode.com/gh_mirrors/mm/MMKV

点击查看免费下载

导读

本指南以仓库根目录的 CHANGELOG.md（共 1093 行，覆盖 2018 年 9 月 v1.0.10 至 2026 年 8 月 v2.4.2 的全部版本记录）为骨架，系统梳理 MMKV 八年来的版本脉络：每一个大版本的核心能力（AES-256 加密、统一回调、NameSpace、Mayfly FD、Kotlin Multiplatform）、每一次破坏性变更的迁移路径、每个平台的支持矩阵变化。读完本文，你将能够：快速判断某个能力在哪个版本引入、评估从旧版本升级的风险点、并借助源码文件位置（Core/MMKV.h、Android 侧 Java 接口、KMP 公共接口）亲自验证每一条变更的真实实现。

版本发布总览：三大代际与两类版本线

从 CHANGELOG 的版本号与发布节奏可以归纳出 MMKV 的演进规律：

代际	版本范围	时间跨度	核心主题
v1.0.x	v1.0.10 ~ v1.0.24	2018-09 ~ 2020-01	平台铺开（iOS/macOS/Android/Windows）、错误回调、trim/close
v1.1.x	v1.1.0 ~ v1.1.2	2020-03 ~ 2020-05	统一 Core 库、POSIX 支持、iOS 多进程、CRC 恢复策略
v1.2.x	v1.2.0 ~ v1.2.16	2020-06 ~ 2023-04	内存占用减半、backup/restore、静态 libc++、Flutter/golang/Python
v1.3.x（LTS）	v1.3.0 ~ v1.3.9	2023-06 ~ 2024-07	auto key expire、C++20、HarmonyOS NEXT 首支持
v2.0.x	v2.0.0 ~ v2.0.2	2024-10 ~ 2024-12	只读模式、Android 15 16K page、API 23 下限
v2.1.x	v2.1.0	2025-02	NameSpace（Android/OHOS 破坏性变更）
v2.2.x	v2.2.0 ~ v2.2.4	2025-04 ~ 2025-09	Mayfly FD、Flutter 桌面端、importFrom/checkExist
v2.3.x	v2.3.0	2025-12	AES-256 加密（破坏性变更）
v2.4.x	v2.4.0 ~ v2.4.2	2026-03 ~ 2026-08	统一 MMKVHandler、MMKVConfig、C bridge、KMP

两条版本线需要区分：v2.x 主线不断引入新特性（同时伴随破坏性变更），而v1.3.x LTS 系列（v1.3.7、v1.3.9）只修关键 bug、不再加新功能。CHANGELOG 明确说明："only critical bug fixes will be applied to the 1.3.x series. New features will be introduced in version 2.0 and later"。同时注意 Flutter 从 v1.3.0 起版本号与原生库保持一致。

v2.4.x：近期热更、KMP 实验支持与通用 C 桥

v2.4.2（2026-08-21）：基于 v2.4.1 的定向热修复

v2.4.2 是一次 hotfix 发布，聚焦四类问题：

加密与写入加固：加固了加密随机 IV 生成、密钥安全清理、加密模式切换，以及受边界约束的 protobuf 写入；
备份/恢复安全：防止通过等价目录别名进行自我备份/恢复、修复未缓存备份的加锁问题、拒绝不完整的恢复源、正确处理以.crc结尾的 ID；
过期常量修正：修正了一年期过期常量，此前在 Android、iOS/macOS、HarmonyOS NEXT、Flutter、Go 上该常量实际代表 30 年；
构建修复：目录遍历支持长路径，PBUtility.h直接包含其依赖的MMBuffer头。

各平台细节：KMP 修复了空字节数组与 UTF-8 字符串在各 target 间的一致性，以及 Android/iOS 上键校验与过期行为对齐（包括统一拒绝含内嵌 NUL 的键）；iOS/macOS 修复了安全擦除密钥在 Apple 平台上的编译问题（issue #1675）；HarmonyOS NEXT 向 OHPM 元数据补充了包作者邮箱；Flutter 修复 SwiftPM 构建下 Dart FFI 入口在 iOS/macOS 的链接导出问题（issue #1676）；Win32 修复了 MSVC 下 C 桥编译及其 UTF-8/宽路径边界（issue #1681）。构建侧新增了可复用的、带保护的产物清理脚本（Scripts/clean-generated.sh）。

v2.4.1（2026-07-30）：维护版本 + 通用 C 接口 + KMP 实验版

v2.4.1 是数据安全与打包清理为主线的维护版本，亮点有三：

1. 数据安全修复（全平台）

实例生命周期：更安全的 wrapper 所有权、原生锁的销毁、明确close()的破坏性语义（C 桥头文件中明确：mmkv_close后所有引用立即失效，且该操作不得与其他操作并发）；
超长键损坏 bug：超过内部uint16_tholder 上限的键会溢出键/值元数据并破坏后续读取，已修复（POSIX 侧补了回归测试）；
expireDuration 溢出（issue #1665）：极大的过期时长现在被安全钳制而非回绕；
加密随机 IV 升级：使用旧 IV 格式的既有加密文件在可能时触发一次完整 writeback，升级为随机 IV 格式；清空加密实例内存缓存时也有更安全的随机 IV 重置行为。

2. 通用 C 接口（Core/cbridge）新增 Core/cbridge/MMKVBridge.h 与 Core/cbridge/MMKVBridge.cpp，以纯 C ABI 暴露 MMKV Core 全部能力，支持 NameSpace，并附带纯 C demo（POSIX/demo/demo_c.c）。其MMKVConfig_t与MMKVHandler_t结构完整映射了 C++ 侧的配置与回调（见下节），KMP iOS 包也正是通过该 C 桥嵌入 MMKV Core。

3. Kotlin Multiplatform（实验性）通过 Gradle 包com.tencent:mmkv-kmp:2.4.1首次加入 Android/iOS 的 KMP 支持（官方标注 API 与产物布局未来可能变化），支持 Android、iosArm64、iosSimulatorArm64、iosX64四个 target。Android 委托给原生com.tencent:mmkv:2.4.1AAR，iOS 通过 C 桥将 Core 嵌入发布的原生 KLIB。公共接口位于 KMP/mmkv/src/commonMain/kotlin/com/tencent/mmkv/kmp，包含MMKV（expect class，含defaultMMKV()与defaultMMKV(config)）、MMKVConfig（data class）、MMKVHandler（abstract class）、MMKVMode、MMKVExpireDuration、MMKVNameSpace等。

其他要点：iOS/macOS 新增 SwiftPM 静态产物MMKVAppExtension-static，并新增拼写正确的+[MMKV unregisterHandler]（此前拼错的+unregiserHandler保留用于源码/二进制兼容并转发到新 API）；Flutter 增加 SwiftPM 支持并迁移示例（CocoaPods 保留为后备）；Android 增加过期溢出回归覆盖并改进 CMake 头文件导出检测。

v2.4.0（2026-03-18）：统一回调接口与一键配置

v2.4.0 是本仓库"回调系统重构"的分水岭：

统一 MMKVHandler 接口：此前分散的registerLogHandler()/registerErrorHandler()/registerContentChangeHandler()/registerContentLoadedHandler()被全部移除，改为通过registerHandler()注册一个 OO 风格的统一 handler。Android 侧实现见 Android/MMKV/mmkv/src/main/java/com/tencent/mmkv/MMKVHandler.java，其 8 个方法覆盖：onMMKVCRCCheckFail(mmapID)（crc32 校验失败处理，返回 MMKVRecoverStrategic 决定丢弃还是恢复）、onMMKVFileLengthError(mmapID)（文件长度异常）、wantLogRedirecting()/mmkvLog(level, file, line, function, message)（日志重定向）、getNativeLogHandler()（返回 C++ 侧原生日志处理函数指针，v2.2.3 新增）、wantContentChangeNotification()/onContentChangedByOuterProcess(mmapID)（跨进程内容变更通知）、以及新增的onMMKVContentLoadSuccessfully(mmapID)（文件加载/映射成功后回调）。Android 的MMKVContentChangeNotification接口被合并进MMKVHandler，旧接口标记@Deprecated（Android/MMKV/mmkv/src/main/java/com/tencent/mmkv/MMKVContentChangeNotification.java）。C++ 侧注册入口为MMKV::registerHandler(mmkv::MMKVHandler *handler)（Core/MMKV.h 第 662 行）。

MMKVConfig 一键配置：新增MMKVConfig聚合全部实例选项。C++ 定义见 Core/MMKV.h 第 72-91 行，Android 版见 Android/MMKV/mmkv/src/main/java/com/tencent/mmkv/MMKVConfig.java，字段一一对应：

字段	默认值	含义
`mode`	`SINGLE_PROCESS`	进程模式（单进程/多进程/只读）
`aes256`	`false`	是否使用 AES-256 密钥长度
`cryptKey`	`null`	加密密钥，`null`表示不加密
`rootPath`	`null`	自定义根目录（绝对路径）
`expectedCapacity`	`0`	初始文件大小
`enableKeyExpire`	`null`	是否启用自动键过期（`null`表示保持默认）
`expiredInSeconds`	`0`	过期秒数（`0 = ExpireNever`）
`enableCompareBeforeSet`	`false`	写入前是否先比较新旧值
`recover`	`null`	磁盘损坏恢复策略，不设则走旧式回调
`itemSizeLimit`	`0`	单个键值对大小上限，超限拒绝写入

同时新增defaultMMKV(config)变体，用于以完整配置创建默认实例。

其余修复：加密模式健壮性检查（issue #1642）、损坏文件上delete失败的防护、m_file无效时isDiskOfMMAPFileCorrupted()的防护、减少absolutePath()调用、Androidfcntl()OFD 锁在 ashmem 上失败的问题（issue #1637）、iOS/macOS 增加string_view键的getBytes()与 NameSpace 实例内存泄漏修复。注意 v2.4.0 起 MMKV 必须以 C++17 编译，并放弃旧式 actual size 降级支持。

v2.3.0（2025-12-03）：AES-256 加密的破坏性变更

v2.3.0 的核心是引入AES-256 加密。升级路径在 CHANGELOG 中写得非常明确：要升级既有加密实例，需先用旧密钥加载实例，再调用reKey(newKey, aes256=true)完成密钥与加密算法升级，此后所有加载都必须使用新密钥。C++ 侧对应 Core/MMKV.h 第 368 行的bool reKey(const std::string &cryptKey, bool aes256 = false)，多进程场景还需配合checkReSetCryptKey()（第 372 行）在另一进程同步新密钥状态。

该版本同时是破坏性变更版本：

Apple Watch 放弃 armv7k：需要 armv7k 支持的工程必须在 Watch App/Extension 的 "Excluded Architectures" 中加入armv7k，否则不要升级；
POSIX 放弃 armv7：同理，需要 armv7 支持的场景不要升级；
iOS/macOS 移除relativePath:废弃方法：必须迁移到rootPath:参数版本。

此外还修复：ReadOnly模式下加载空文件的崩溃、无效文件路径触发weakly_canonical()异常的防护、多进程加载期间文件尺寸变化的竞态、以及从 v1.1.x 升级时单键被错误覆盖的问题。

v2.2.x：Mayfly FD、Flutter 全桌面与效率提升

v2.2.0（2025-04-24）引入 Mayfly FD（短生命周期文件描述符）：单进程模式实例的 fd 占用降为零（Android/OHOS 仍需一个常驻 fd 支撑进程模式检查与遗留命名升级），多进程模式因需常驻 fd 做进程间锁，fd 占用减半；多进程访问效率提升约 20%。同时新增checkExist()静态方法（C++ 见 Core/MMKV.h 第 678 行，用于检查磁盘上是否存在某实例）与importFrom()（第 609 行，把另一实例的数据导入当前实例），并放弃废弃的 armv7 AES 硬件加速。Android 侧升级 compileSdk/targetSdk 至 35、NDK 至 28.1、Java 11、Gradle 8.11.1、AGP 8.9.2；iOS 新增+mmkvGroupPath获取多进程存储的 group 目录；HarmonyOS NEXT 移除从未使用的checkProcessMode()；Flutter 新增isFileValid()与 iOSgroupPath()。

v2.2.3（2025-08-20）为 Flutter 补全桌面端：Windows、macOS、Linux 正式受支持，示例应用覆盖全部桌面平台。Android 新增MMKVHandler.getNativeLogHandler()（原生日志处理，提升性能），修复原生内存地址超过Long.MAX_VALUE被判为负数的整数溢出、JNI 局部引用未释放的潜在内存溢出、特殊相对路径目录创建失败，并增强回调 handler 的线程安全。iOS/macOS 修复MMKV_APPLE未定义时的编译错误与 Swift 命名冲突；Windows demo 转 UTF-8 修正字符编码。

v2.2.2（2025-05-08）是 Android/Linux 平台的强推热更：修复 Mayfly FD 实例的文件锁一致性问题、Android/POSIX 多进程模式初始化潜在的 ANR、iOS 短生命周期回调 handler 崩溃、Win32 初始化效率。

v2.1.0（2025-02-18）：NameSpace 与 Android/OHOS 破坏性迁移

v2.1.0 新增NameSpace 特性，轻松支持自定义根目录（C++ 侧MMKV::nameSpace(rootDir)/defaultNameSpace()，见 Core/MMKV.h 第 339-342 行，Android 侧实现为 Android/MMKV/mmkv/src/main/java/com/tencent/mmkv/NameSpace.java）。

但该版本对 Android/OHOS 是breaking change：历史上 Android/OHOS 误把 mmapKey 当作 mmapID 使用，在 NameSpace 特性下会产生问题，v2.1.0 起 MMKV 会尽可能把自定义目录中的遗留 MMKV 迁回正常命名。官方迁移建议非常关键：升级到 v2.0.2/v1.3.11 时先依赖其对自定义目录正常 MMKV 的前向支持，再升级到 v2.1.0。iOS/macOS 为支持 NameSpace 将最低版本提升至 iOS 13 / macOS 10.15 / watchOS 6，并借此放弃 iOS 13+ 的后台mlock()保护（WeChat 实测已无需）。其余：所有平台新增磁盘坏记录防护（iOS/Win32 为 tested，Android/OHOS/POSIX 为 experimental），文件锁改用F_OFD_SETLK替代F_SETLK，各平台均支持在 C++ 中直接使用 MMKV。

v2.0.x：只读模式、Android 15 与 32 位告别

v2.0.0（2024-10-21）是破坏性版本，尤其对 Android：新增只读模式（C++ 侧枚举MMKV_READ_ONLY，见 Core/MMKV.h 第 56-65 行的MMKVMode）；Android 支持 16K page size（Android 15）、放弃 32 位 ABI、最低SDK 升至 API 23；iOS/macOS 增加 Mac Catalyst 支持；Flutter/HarmonyOS NEXT 增加 log/error/content-change 回调。

v2.0.1（2024-11-12）热更：修复解码容器类型值后其他线程可能死锁的 bug——HarmonyOS NEXT 的decodeStringSet()/decodeNumberSet/decodeBoolSet/TypedArray解码、POSIX 的std::vector<T>/std::span<T>解码均受影响。

v2.0.2（2024-12-27）：修复跨文件系统 backup/restore 失败、auto-key-expire 实例的非法 value size 防护；Android 在 32 位 App 加载原生库前抛UnsupportedArchitectureException（见 Android/MMKV/mmkv/src/main/java/com/tencent/mmkv/UnsupportedArchitectureException.java）；Android/OHOS 对自定义根目录的正确文件名提供前向支持。

v1.3.x LTS：自动过期、C++20 与 HarmonyOS 首秀

v1.3.0（2023-06-14）引入 auto key expiration（自动键过期），注意这是破坏性变更：一旦开启自动过期，旧版本（v1.2.16 及以下）无法正确操作该文件。同时回滚了 v1.2.16 的 lazy load（因 ANR 报告），v1.3.3 又重新带回（确认 bug 由别处引起）。

v1.3.2（2023-11-20）贡献了大量实用特性：自定义实例初始文件大小；单进程模式下仅含一个键时、以及零键时从文件头覆盖写入的写速度优化；clearAll()保留磁盘空间的选项（默认关闭，需传参调用，减少后续扩容）；写入前先比较同键值（enableCompareBeforeSet）；文件扩容成功但zeroFill()失败导致的无效状态崩溃修复；其他模块关闭 RTTI 导致std::exception无法捕获的崩溃修复。Android 默认-O2减小 so 体积并微提速。该版本还记载了 Xcode 15 的已知问题（iOS 14 及以下崩溃），Apple 官方解法为-Wl,-weak_reference_mismatches,weak或-Wl,-ld_classic链接选项。

v1.3.3（2024-01-25）新增removeStorage()静态方法安全删除实例底层文件（C++ 见 Core/MMKV.h 第 675 行）；优化加载速度（除罕见的截断需求外使用共享进程间锁）；Android 修复空 ByteArray 返回 null、AGP 8 包命名空间错误等问题。

v1.3.5（2024-04-24）HarmonyOS NEXT 首次正式支持（此前 v1.3.4 已支持 visionOS）；Flutter 迁移到 federated plugins 消除 iOS 改名问题；iOS/Android 最低版本均升至 iOS 12 / API 23，Android 放弃 armv7 与 x86。

v1.3.6（2024-07-05）Core 升级到 C++20：键类型从std::string改为std::string_view，避免原始字符串键的构造/析构开销；引入Concept与以string_view为键的 unordered 容器。源码级佐证见 Core/MMKV.h 的MMKV_SUPPORTED_PRIMITIVE_VALUE_TYPE等 concept 定义，以及 POSIX/Win32 支持std::vector<T>/std::span<T>的编解码。该版本起源码构建需要支持 C++20 的编译器（仅用二进制产物则不受影响）。HarmonyOS NEXT 修复 String 截断，且不存在的键返回undefined而非类型默认值（false/0）。

v1.3.7/v1.3.9（LTS）：v1.3.7 是 LTS 版本，重新支持 ARMv7、最低 SDK 降至 21；v1.3.9 修复"仅存一个键值的加密 MMKV 数据损坏 bug"、使加密更抗暴力破解、修复pthread_mutex未正确销毁，NDK 升至 26.3。

v1.2.x：内存减半与生态扩展

v1.2.0（2020-06-30）是第二个大版本，底层全面重构：

内存占用近乎减半（非加密实例）：不再用字典缓存全部键值，改为在 mmap 内存中直接存储每个键值对的 offset；加密实例因需存加密信息，仅对 >256B 的大键值存 offset；
写回效率：基于 offset 方案用多次memmove()实现写回；
小键值优化：MMBuffer结构把小型值（所有基本类型）存入栈而非堆，省去大量malloc()/free()；
iOS/macOS 用 mmap 中的 UTF-8 键取代实时编码，优化既有键的插入/删除；放弃 iOS 8（thread_local不可用）。

后续版本继续丰富：v1.2.2增加 iOS 自动清理（enableAutoCleanUp:）与 Android 多进程模式检查（误用SINGLE_PROCESS_MODE会抛IllegalArgumentException）；v1.2.5/v1.2.6/v1.2.7先后加入 Flutter、golang（POSIX）、Python（POSIX）支持，以及MMKV_DISABLE_CRYPT宏裁剪加密能力；v1.2.8迁移至 Maven Central、Android 默认静态链接libc++（com.tencent:mmkv-static与com.tencent:mmkv合并，需要动态库的用com.tencent:mmkv-shared）；v1.2.11全平台加入backup & restore 能力（C++ 静态方法backupOneToDirectory/backupAllToDirectory/restoreOneFromDirectory/restoreAllFromDirectory，见 Core/MMKV.h 第 641-656 行）；v1.2.16引入 lazy load（后经反复，v1.3.3 定型）。

v1.1.x / v1.0.x：统一 Core 与全平台生根

v1.1.0（2020-03-24）是 MMKV 开源（2018 年 9 月）后的第一个大破坏性版本，四大成就至今仍是架构基石：

统一 Core 库：重构整个项目，iOS/macOS、Android、Windows 共享同一套核心逻辑（本仓库根目录的 Core/ 目录即这一重构的产物）；
文件恢复策略改进：每次 sync/全量写回时存储 CRC 校验和与实际文件大小于.crc元数据文件，WeChat iOS 实测将文件损坏率降低近一半；
POSIX 平台支持与iOS/macOS 多进程访问（通过 app group 初始化）；
armv8 设备的 AES 与 CRC32 指令加速，加密与校验速度提升一个数量级。

v1.0.x则见证了平台与 API 的铺开：v1.0.11 支持 macOS 与 NSCoding；v1.0.13 增加错误处理回调（crc32 失败可恢复而非丢弃）与 trim/close，支持特殊字符 mmapID（md5 编码存入独立目录）；v1.0.15 直接存储 NSString/NSData/NSDate；v1.0.16 自定义根目录/自定义实例目录与getValueSizeForKey；v1.0.17 日志重定向与动态关闭、自定义LibLoader（可配合 ReLinker）；v1.0.18 引入Native Buffer（见 Android/MMKV/mmkv/src/main/java/com/tencent/mmkv/NativeBuffer.java）；v1.0.19 支持 Android Q、异步sync()/apply()、allKeys()；v1.0.23 修复加密 MMKV 的潜在安全泄漏、增加跨进程内容变更通知（MMKVContentChangeNotification接口）。

破坏性变更速查与升级路线

把 CHANGELOG 中的 breaking change 汇总为一张升级检查清单：

版本	破坏性变更	应对措施
v1.1.0	首个大版本重构	遵循当时的初始化迁移说明
v1.2.1	`relativePath`重命名为`rootPath`（绝对路径语义）	迁移到`rootPath:`API
v1.3.0	auto key expire 开启后旧版本无法读文件	开启前评估回滚可能
v1.3.6	源码构建需 C++20 编译器	升级编译器；二进制用户无感
v2.0.0	Android 放弃 32 位 ABI、最低 API 23	发布 64 位产物、提升 minSdk
v2.1.0	Android/OHOS 自定义目录遗留命名迁移	先升 v2.0.2/v1.3.11 再升 v2.1.0
v2.3.0	AES-256 引入；armv7k（watchOS）/armv7（POSIX）放弃	用`reKey(newKey, aes256=true)`升级；需要老架构则不升级
v2.4.0	四个 per-callback 注册 API 移除，统一为`registerHandler()`；C++17 要求	迁移到统一`MMKVHandler`；源码构建者升级编译器

加密升级的推荐路径是：先升级到 v2.3.0 之前的版本完成数据层面过渡，再在 v2.3.0+ 用旧密钥加载、reKey()换新密钥并开启aes256，随后统一使用新密钥加载。Android 多进程场景在reKey()后需调用checkReSetCryptKey()同步其他进程。

如何用仓库源码验证每条变更

CHANGELOG 记录与源码一一对应，验证时可遵循以下路径：

统一回调与一键配置：Core/MMKV.h（MMKVConfig结构体第 72-91 行、registerHandler第 662 行）、Android/MMKV/mmkv/src/main/java/com/tencent/mmkv/MMKVHandler.java、Android/MMKV/mmkv/src/main/java/com/tencent/mmkv/MMKVConfig.java；
C 桥：Core/cbridge/MMKVBridge.h（MMKVConfig_t/MMKVHandler_t）、Core/cbridge/MMKVBridge.cpp、POSIX/demo/demo_c.c；
KMP 实验支持：KMP/mmkv/src/commonMain/kotlin/com/tencent/mmkv/kmp/MMKV.kt（expect class 与defaultMMKV(config)）、KMP/mmkv/src/commonMain/kotlin/com/tencent/mmkv/kmp/MMKVConfig.kt；
NameSpace 与自定义目录：Core/MMKV.h 第 339-342 行、Android/MMKV/mmkv/src/main/java/com/tencent/mmkv/NameSpace.java；
备份/恢复/删除/检查：Core/MMKV.h 第 641-656 行（backup/restore）、第 675 行（removeStorage）、第 678 行（checkExist）；
Android 各平台实现：Android/MMKV/mmkv/src/main/java/com/tencent/mmkv/MMKV.java 及其 Native 桥 Android/MMKV/mmkv/src/main/cpp/native-bridge.cpp；
POSIX demo 回归测试：POSIX/demo/UnitTest.cpp（v2.4.1 新增的超长键拒绝与过期溢出回归覆盖）。

结语：从 CHANGELOG 中可以学到什么

通读这份 CHANGELOG，能清晰地看到 MMKV 的工程方法论：先铺平台（v1.0.x 生态扩张）→统一内核（v1.1.0 的 Core 重构）→内存与性能纵深优化（v1.2.0 起）→功能与安全并进（自动过期、AES-256、随机 IV）→跨语言、跨框架开放（Flutter、KMP、C bridge）。每一次破坏性变更都伴随明确的迁移指引与"是否可回退"的说明，LTS 分支与主线并行、hotfix 独立成版——这些都是大型开源存储组件值得借鉴的发布纪律。对本仓库用户而言，这张版本路线图就是一份现成的升级风险评估手册：先对照破坏性变更速查表确认影响面，再用文末的源码路径逐条验证，即可把升级成本降到最低。