Android数据存储进化：从SharedPreferences到DataStore实战指南

1. 为什么我从 SharedPreferences 转向 DataStore做 Android 开发的人几乎没有人没写过 SharedPreferences。轻量、简单、API 熟悉存个登录状态、缓存个开关配置几行代码就完事。但你要是在稍微有点规模的项目里待过一段时间就会慢慢发现它的种种不顺手apply() 和 commit() 的行为差异、数据更新没法观察、多进程下读取不可靠、跨页面同步只能手动刷——这些痛点在小项目里还能忍一旦团队协作规模上来就开始拖后腿。DataStore 就是在这个背景下出现的替代方案。它由 Jetpack 官方提供基于 Kotlin 协程和 Flow 实现核心能力可以概括为三点以异步方式读写数据、天然支持响应式观察、通过事务机制保证数据一致性。这篇文章我想从我的实际踩坑经历出发把 DataStore 的原理、选型、封装方式和一些官方文档里没写明白的细节一次性讲透尽量让你看完之后真的能把它用明白。内容主要面向已经写过一段时间 Android、对 SharedPreferences 有基础但想迁移到更现代方案的开发者。如果你刚接触 Kotlin 协程和 Flow需要先去补一下这两个基础概念但不要求精通因为 DataStore 的封装层已经把复杂度消化了大部分你只需要理解几个关键约定。先放一个结论DataStore 并不复杂复杂的是它周边的设计决策。Preferences DataStore 和 Proto DataStore 怎么选、Key 怎么设计、文件迁移怎么做、DataStore 实例放哪、出错时的降级策略是什么——这些才是决定一个项目用得好不好的关键。接下来我按实际开发顺序一条条展开。2. DataStore 的核心机制与两种存储模式的取舍2.1 打破 SharedPreferences 的三个核心痛点SharedPreferences 最被人诟病的问题首先是阻塞。commit()是同步写盘如果你在主线程调轻则掉帧重则卡到用户想摔手机。apply()虽然是异步落盘但更新内存是同步的而且它内部会等所有 pending 写入完成处理不好同样会卡。DataStore 的读写全部基于协程的异步流程不会存在“某个线程被卡住等磁盘 ”的情况。其次是不可观察。SharedPreferences 虽然有OnSharedPreferenceChangeListener但它是回调式、非类型安全、还容易漏注册。一个 key 改没改你得靠 log 或者自己写监听器去排查。DataStore 直接把数据变成FlowT天然响应式界面上任何想订阅数据变化的地方只需要一个collect就搞定配合repeatOnLifecycle用起来非常干净。第三个痛点是事务性。SharedPreferences 的多 key 更新没有原子性概念你要同时更新两个 key得自己保证“都成功或都失败”。DataStore 的数据操作在底层会经过一个事务机制处理你要修改数据时会拿到当前数据的不可变快照Snapshot修改后返回新对象事务成功才会落盘失败则不会破坏旧数据这个设计对一致性要求高的场景帮助很大。2.2 Preferences DataStore键值对存储的轻量方案Preferences DataStore 是 SharedPreferences 的最直接替代者用法也非常接近。它的数据存储格式仍然是键值对持有一个DataStorePreferences对象但不再暴露getXxx()/putXxx()这种同步方法而是统一走edit()的挂起函数或updateData()转换函数。实际用起来大致长这样val Context.dataStore: DataStorePreferences by preferencesDataStore( name user_prefs ) val userIdFlow: FlowString? context.dataStore.data .map { preferences - preferences[KEY_USER_ID] }写入时suspend fun saveUserId(userId: String) { context.dataStore.edit { preferences - preferences[KEY_USER_ID] userId } }注意preferencesDataStore是顶层属性委托在文件级别定义保证整个应用内只有一个 DataStore 实例。这个“单例”约束很重要同一个文件如果创建多个 DataStore 实例会因为无法获得文件锁而抛异常。我见过有人在 Application 里定义一遍又在某个 Activity 里定义一遍同名 DataStore结果就是 java.io.IOException: There are multiple DataStores active for the same file。Preferences 模式适合什么样的场景存一些零散配置项、用户偏好、临时状态对类型要求不苛刻不想引入额外编译时依赖——这种场景它是性价比最高的。2.3 Proto DataStore类型安全与结构化数据的进阶选择Proto DataStore 就不一样了。它要求你先定义一个 Protocol Buffers 的 schema.proto文件然后编译生成对应实体类整个 DataStore 的读写都围绕这个类型安全的对象来操作。换句话说你不再操作散落的 key而是操作一个完整的配置对象。一个简单的 schema 定义message UserPreferences { string user_id 1; bool is_logged_in 2; int32 theme_mode 3; }使用 Proto DataStore 需要额外做几步引入 protobuf 编译插件、定义 schema 文件、写一个SerializerT实现类然后才是业务逻辑。这一步引入的成本不算低尤其是项目里本来没接触过 Protocol Buffers 的团队学习曲线会陡一些。它的核心优势有两个。第一是类型安全读出来的一定是定义好的类型不存在的字段在编译期就会暴露问题不会出现 SharedPreferences 那种“Key 写错一个字母运行期返回 null排查半天”的情况。第二是 schema 演进能力字段增删可以通过约定好的编号规则向后兼容老数据自动迁移不需要手动写复杂的版本判断逻辑。结合这两种模式的差异我的建议非常明确如果你的项目已经有 Proto 的生态或者你对数据结构和类型安全有要求选 Proto DataStore如果只是想找一个体验更好、能观察变化的 SharedPreferences 替代品Preferences DataStore 就够了。不要为了“听起来更先进”就强行上 Proto它带来的复杂度是真实存在的。3. Preferences DataStore 实战从依赖接入到完整读写封装3.1 依赖引入与基础配置要点Preferences DataStore 的依赖很简单在 module 的 build.gradle 里加一行implementation(androidx.datastore:datastore-preferences:1.1.1)当前稳定版本以官方发布为准升级前建议查一下 Release Notes。然后是定义顶层扩展属性我习惯放在一个单独的 DataStoreHelper.kt 文件里private val Context.dataStore by preferencesDataStore(name app_preferences) class PreferenceManager(context: Context) { private val appDataStore context.applicationContext.dataStore val isFirstLaunch: FlowBoolean appDataStore.data .map { it[KEY_FIRST_LAUNCH] ?: true } suspend fun setFirstLaunch(value: Boolean) { appDataStore.edit { it[KEY_FIRST_LAUNCH] value } } companion object { private val KEY_FIRST_LAUNCH booleanPreferencesKey(first_launch) private val KEY_USER_ID stringPreferencesKey(user_id) private val KEY_LAST_LOGIN_TIME longPreferencesKey(last_login_time) } }3.2 Key 定义的类型约定与命名规范Preferences DataStore 的 Key 需要通过不同前缀函数创建这是它与 SharedPreferences 最大的不同之一。booleanPreferencesKey()、stringPreferencesKey()、intPreferencesKey()、longPreferencesKey()、floatPreferencesKey()分别对应不同类型读取时要传入同类型的 Key否则会在运行时抛出类型转换异常。我见过不少迁移代码直接在原来 SharedPreferences 的 key 名前加个stringPreferencesKey()就完事结果双端类型对不上日志刷出一堆 cast 异常。这里有个排查技巧DataStore 是单文件存储如果你同时在一台设备上跑新旧两版逻辑老 SharedPreferences 文件里的值不会自动同步到 DataStore 文件里必须显式做迁移否则用户升级后就丢了原来的配置。关于命名规范我的个人经验是不要偷懒。项目里的 Key 最好放在一个集中管理的文件中用前缀区分业务模块比如KEY_USER_、KEY_SETTING_、KEY_CACHE_。不要直接在业务代码里到处写stringPreferencesKey(name)否则三个月后你自己都不知道这个name是哪个页面的。3.3 实战常见坑读取异常降级与 collect 生命周期DataStore 的data流在读取失败时会不会抛异常会。不管什么原因比如文件损坏、反序列化失败它在未捕获时会终止整个 collect 链。官方提供的做法是在map阶段替换异常比如用catch {}捕获上游异常val userPreferences: FlowUserPreferences appDataStore.data .catch { exception - if (exception is IOException) { emit(emptyPreferences()) } else { throw exception } } .map { ... }这段代码我建议每个使用 DataStore 项目的入口处都放一个它保证万一磁盘出问题你拿到的是空数据而不是直接崩溃。FileNotFoundException 已经被 DataStore 内部处理为正常空数据所以不需要额外处理但其他 IOException 和序列化异常必须兜住。还有个生命周期问题在 Activity 里直接lifecycleScope.launch { dataStore.data.collect { ... } }会一直收集到协程结束如果把生命周期销毁的事件漏掉就可能在后台持续浪费资源甚至导致数据竞争。正确姿势是使用repeatOnLifecycle(Lifecycle.State.STARTED)或至少在onStop里 cancel。这一点和 Flow 的通用规范一致但在 DataStore 的场景里更容易被忽略因为它不像网络请求那样明显有“结束”的概念。4. Proto DataStore 完整实操schema 定义、序列化器与迁移4.1 Protocol Buffers 环境搭建与编译配置Proto DataStore 的接入成本主要集中在环境和编译配置上。先在项目根 build.gradle 里声明 protobuf 插件plugins { id com.google.protobuf version 0.9.4 apply false }然后在 app module 里应用plugins { id com.google.protobuf } android { sourceSets { main { proto { srcDir src/main/proto } } } } protobuf { protoc { artifact com.google.protobuf:protoc:3.22.0 } generateProtoTasks { all().each { task - task.builtins { java { option lite } } } } } dependencies { implementation androidx.datastore:datastore:1.1.1 implementation com.google.protobuf:protobuf-javalite:3.22.0 }这里的 lite 模式是专门为移动端裁剪的运行时比完整版生成的代码体积小、反射少Android 上几乎都用这个。如果你以前做过后端开发可能对 PLITE 和 FULL 的区别不敏感但移动端构建产物体积本来就很敏感不建议用完整版。把 schema 文件放进src/main/proto目录同步 Gradle 后重新编译会生成对应的 Java 类类名就是你定义的 message 名加OuterClass后缀如果文件里只有一个 message也可以直接用 message 名生成类看插件配置。4.2 Serializer 实现的关键细节有了生成的类还要自己实现一个SerializerT。网上很多教程直接把这个类草草带过实际上序列化器是 Proto DataStore 中最容易写错的部分。一个完整示例object UserPreferencesSerializer : SerializerUserPreferences { override val defaultValue: UserPreferences get() UserPreferences.getDefaultInstance() override suspend fun readFrom(input: InputStream): UserPreferences { return try { UserPreferences.parseFrom(input) } catch (e: InvalidProtocolBufferException) { Log.e(DataStore, Failed to parse proto, e) UserPreferences.getDefaultInstance() } } override suspend fun writeTo(t: UserPreferences, output: OutputStream) { t.writeTo(output) } }注意三个细节。defaultValue必须返回空对象不能返回 null否则 DataStore 在建第一个文件时拿不到初始数据readFrom里捕获异常后返回默认值保证文件损坏时能恢复而不是崩溃writeTo就是简单把对象序列化到输出流但这个函数是挂起函数它的执行时机由 DataStore 的事务机制保证。定义好序列化器后DataStore 实例的创建方式就变了val Context.userPreferencesDataStore: DataStoreUserPreferences by dataStore( fileName user_preferences.pb, serializer UserPreferencesSerializer )文件后缀我一般建议用.pb而不是随便一个名字。它和 Preferences 模式的.preferences_pb后缀区分开方便排查文件时一眼看出是哪种类型的存储。4.3 读取与更新 Proto 数据的操作模式Proto 模式数据的读取就是直接拿对象val userData: FlowUserPreferences context.userPreferencesDataStore.data val userName: FlowString context.userPreferencesDataStore.data .map { it.userName }更新时则是先读后写在updateData()里从旧对象创建一个新的副本suspend fun updateThemeMode(mode: Int) { context.userPreferencesDataStore.updateData { currentPrefs - currentPrefs.toBuilder() .setThemeMode(mode) .build() } }这就是面向不可变对象的更新模式。toBuilder()会复制当前对象的所有字段然后只修改你要改的部分。它保证哪怕别人先更新了另一个字段你的修改也不会覆盖掉他。这个机制和 Kotlin 的 data class copy 很像但 Proto 的 toBuilder 是 Java 风格。4.4 从 SharedPreferences 或旧 Preferences DataStore 迁移数据从 SharedPreferences 迁移到 DataStore有两套方案。简单粗暴的方案是放弃旧数据首次使用新 Key 时给默认值优雅的方案是用 DataStore 提供的SharedPreferencesMigrationval Context.dataStore: DataStorePreferences by preferencesDataStore( name user_prefs, produceMigrations { context - listOf(SharedPreferencesMigration(context, legacy_shared_prefs)) } )这个迁移 API 会自动把旧 SharedPreferences 文件里的键值对读到 DataStore 文件里并且可以通过SharedPreferencesMigration的 keys 参数指定只迁移一部分 key。如果你是从 Preferences DataStore 迁移到 Proto DataStore那过程就复杂一些需要在 Proto 定义的 schema 里通过DataStoreMigration手动把 Preferences 的键值转换成新的 Proto 字段。关于迁移我踩过一个很隐蔽的坑迁移只会在第一次读取或第一次写入时触发而不是 DataStore 对象创建时触发。如果你在迁移逻辑里依赖别的 DataStore 或 Room 的数据一定要保证它们也已经被初始化否则会读到半成品数据。另外一旦迁移完成旧文件就会被标记删除所以上线前一定要备份验证别指望还能找回。5. 数据安全与协程配合IOException 处理、文件存储原理与 Flow 生命周期5.1 DataStore 文件到底存在哪里为什么它不用 xml 了SharedPreferences 的数据存在/data/data/包名/shared_prefs/应用名.xml一个明文 xml 文件。而 DataStore 用 Protocol Buffers 序列化存成二进制文件路径在/data/data/包名/files/datastore/数据源名.preferences_pbPreferences 模式或自定义的.pb文件。这也解释了为什么 DataStore 读取时不需要像 SharedPreferences 一样做 xml 解析——二进制格式读写更快体积更小。这个差异在你用 adb 调试时会很明显。adb shell去看 shared_prefs 目录随手 cat 能看到内容去看 datastore 目录直接 cat 出来是一堆不可读的二进制。想快速验证数据内容少用命令行 cat直接在代码里通过 DataStore 暴露的 data 流打印即可。另外DataStore 的写入不是每次都物理落盘。底层通过SimpleActor机制串行处理所有修改请求每次updateData的结果会在协程调度器的某个时机写入文件。如果你的应用进程在写入尚未完成时被杀掉可能存在丢失最新一次写入的小概率事件。所以对于真正不可丢失的数据比如用户最后登录凭证不要只依赖 DataStore 达到“强一致”更保险的做法是在上层加策略。5.2 为什么我建议给 DataStore 数据流加一个统一 catch 防线DataStore 官方文档里有一段catch的示例代码基本上是每个data使用处的标配。这里我想再深入讲讲为什么这个防护如此重要。DataStore 存储文件的损坏概率比 xml 高一点原因在于它可能在前一次写盘中途被系统杀掉导致文件处于“半写入”状态。当前版的 DataStore 读文件时有校验和机制检测到损坏会走异常处理但这个异常送到上层如果不拦截照样会终止用户的正常流程。所以我在项目的 DataStore 入口处都会做一个统一封装。思路非常简单核心代码就几行fun T FlowT.dataStoreCatch(): FlowT catch { e - if (e is IOException) { emitAll(flowOf(...)) // 走默认值逻辑 } else { throw e } }这样在业务层接收时无论什么来源都先经过dataStoreCatch()过滤避免在十几处map里重复粘贴catch代码。老项目重构时这种重复代码尤其容易漏统一封装能少很多事。5.3 DataStore 与 ViewModel / UseCase 协作的正确姿势DataStore 是数据层的东西理论上不该直接暴露给 ViewModel 或 Composable。你要想清楚业务层面对的数据源是什么接口。我习惯把 DataStore 藏在 Repository 后面interface UserPreferenceRepository { val userId: FlowString? suspend fun setUserId(id: String?) }ViewModel 只依赖接口class MainViewModel(repository: UserPreferenceRepository) : ViewModel() { val userId: StateFlowString? repository.userId .stateIn(viewModelScope, SharingStarted.Eagerly, null) }UI 层拿到的就是已经集成的StateFlow不需要感知 DataStore 的细节。这样将来你从 Preferences DataStore 迁移到 Proto DataStore只需改动 Repository 实现类上层完全不感知。协程的stateIn里有个重要参数SharingStarted。我实际开发中不建议无脑用WhileSubscribed(5000)它意味着只有订阅才会启动上游 Flow 收集适合保存大量计算结果的场景。DataStore 的数据量很小内存占用也极小用Eagerly反而简单启动时就把最新值准备好后续 UI 订阅立即拿到当前值不用等冷流启动。6. DataStore 常见报错与应对速查表报错信息或现象常见原因解决方案java.io.IOException: There are multiple DataStores active for the same file同一文件创建了多个 DataStore 实例用顶层委托或单例持有确保全应用同一文件只有一个实例kotlinx.coroutines flow 收集后界面不刷新Activity 内 collect 协程未处理生命周期用 repeatOnLifecycle(STARTED) 包裹 collectClassCastException 读取时类型不对key 创建时类型和读取时类型不一致检查所有 key 的前缀函数是否统一线上偶发崩溃kotlinx.coroutines.channels.ClosedSendChannelException某些旧版本 bug升级 DataStore 库到最新稳定版升级版本后旧数据丢失未配置迁移逻辑使用 SharedPreferencesMigration 或自定义 Migration文件损坏、读取异常导致流程中断磁盘 IO 异常或断点写入在数据流入口处统一 catch IOException降级为默认值应用重启后修改的值还是旧值写操作未完成时进程被杀判断写入是否为关键数据必要时结合其他持久化方案这张表里我特别想讲“升级版本后旧数据丢失”这一条。有些团队在 DataStore 版本升级后发现用户配置全部清空以为是迁移 bug其实是因为 DataStore 文件的文件名变了。你原来叫user_prefs.preferences_pb升级后如果因为某种原因换成了new_user_prefs.preferences_pb那新文件自然没有旧数据。这种问题排查方式很简单adb 看下 datastore 目录下有多少个.pb文件如果多出一个陌生的文件名八成就是实例名改了。7. 多模块项目中的 DataStore 设计避免滥用单例与统一数据访问层7.1 DataStore 实例应该放在哪一层这个问题团队里经常有分歧。有人想在 feature 模块各自定义自己的 DataStore也有人想把所有数据集中到 core:data 模块统一管理。我的建议是只在数据模块或 core 模块里持有 DataStore 实例业务模块通过仓库接口访问。原因有两个。第一是避免文件过多。DataStore 每个实例对应一个独立文件如果你的每个模块都建一个 DataStore项目跑一段时间后 datastore 目录下会散落几十个.pb文件排查问题时要挨个看是哪个模块的。第二是避免给业务模块引入 DataStore 依赖。业务层只需要知道“从仓库拿数据”没必要知道它的实现细节这样将来如果框架替换比如从 DataStore 换成 Room 做缓存业务模块代码完全不用动。但也要小心另一个极端所有配置类数据揉进一个 DataStore 文件。如果团队有多个模块同时在写同一个文件就可能出现频繁的读改写竞争updateData的串行事务会排队执行虽然不会出错但会让写入变得很慢。更合理的粒度是把“更新频率高”和“更新频率低”的数据拆成两个 DataStore 文件比如用户操作状态一个文件应用级配置一个文件。7.2 为什么我不建议在 Activity / Fragment 里直接持有 DataStore很多人为了方便直接在 Activity 里写val dataStore context.dataStore。短时间用起来确实方便但你会遇到两个问题。第一个是作用域。Activity 重建时如果同一个 file 的 DataStore 在旧 Activity 和新 Activity 之间同时存在严格来说这个 DataStore 的持有者是 Context不是 Activity 本身所以不存在 Leak 问题。但你会发现想在 Fragment 里读一个值变得很绕必须传 Context代码耦合越来越重。第二个是测试。单元测试时如果 Activity 持有 DataStore就必须 mock 掉整个 Context然后才能测业务逻辑。而如果数据访问封装在 Repository 里测试时只需要 mock Repository 接口清爽得多。7.3 把 DataStore 用法抽象成仓库层后写业务代码的体验抽象完成后业务代码写起来会非常顺class LoginViewModel( private val userRepository: UserRepository, private val settingRepository: SettingRepository ) : ViewModel() { val isLoggedIn userRepository.isLoggedIn.stateIn( viewModelScope, SharingStarted.Eagerly, false ) fun login(userId: String) { viewModelScope.launch { userRepository.saveUserId(userId) } } }UI 层不管是 Activity 还是 Compose都只关心这个StateFlow。数据来源是 Preferences DataStore 还是 Proto DataStore对 UI 完全透明。这也意味着你现在写好的业务代码未来就算 DataStore 底层 API 有破坏性更新你的业务层也可能一行都不用改。8. DataStore 性能实测观察与选型终判8.1 写入性能对比我压测了三种方案我用一台中端测试机分别测过 SharedPreferences、Preferences DataStore、Proto DataStore 在连续写入 100 次小数据时的耗时表现。结论是单次写入性能差异并不明显都能做到几十毫秒以内但连续高频写入时SharedPreferences 的apply()会因为内部队列阻塞产生偶发卡顿DataStore 的两个版本则更稳定。由于 DataStore 的写入是挂起函数接在协程里你没法在主线程上做同步等待这也逼着你把写操作放到后台作用域实际体验反而更顺滑。但别把 DataStore 理解为“一定比 SharedPreferences 快”它不是性能银弹。它的优势主要在一致性、可观察性和类型安全。如果你的应用对写入频率极度敏感比如每秒几十次写入的实时打点缓存我更建议你考虑 Room 或其他更专门的数据方案DataStore 并不适合做高频事件流存储。8.2 什么时候你该用 Preferences什么时候该用 Proto做一个明确选型判断只有一个或几个零散配置值用 Preferences DataStore。配置项之间有强关联关系如“用户信息”里的姓名、头像、ID或者未来会新增字段用 Proto DataStore。已有后端 Proto 契约移动端只需要做本地持久化重点考虑 Proto DataStoreschema 还可以和后端共用。团队没有接触过 Protocol Buffers也没有精力学习和维护生成代码Preferences DataStore 是最低风险的选择。这个判断不是定死的你可以先用 Preferences 做到 80 分等需求复杂了再规划迁移。但迁移成本要提前测一遍尤其是从 Preferences 到 Proto 的过程省不了功夫。8.3 官方文档没有写透的隐藏特性DataStore 的读写顺序保证DataStore 的updateData有一个很重要的特性对同一个 DataStore 文件的更新请求是按提交顺序执行的。这意味着你在协程 A 里写入 A 值、协程 B 里写入 B 值最终文件里的结果一定是按请求到达的顺序不是按协程执行顺序。这个保证可以用来简化业务逻辑比如你不需要自己做版本号比对后写入的一定覆盖先写入的。但这个特性也带来一个隐性问题如果你同时发起很多不相关的写入操作它们会排队执行单次写入慢时会阻塞后面的写入。高并发场景下要对写入频率做削峰。我在项目里用过一种简单粗暴的削峰策略统一走一个应用级写队列把同一时刻的多个写操作合并成一个。不过这种优化不建议一开始就做等真的出现写入排队导致掉帧再引入也不迟。9. 一些我建议你立刻用起来的封装细节与团队规范最后分享几个我在多个项目里验证过的细节。第一个是命名规范。DataStore 的文件名和 Key 名团队成员之间一定要定好约定否则协作起来非常痛苦。文件名的建议是按业务域命名比如user_prefs、setting_prefs、cache_prefs。Key 的命名建议带上模块前缀比如KEY_SETTING_THEME、KEY_USER_ID这种让新人看代码时候能快速定位。第二个是统一错误降级。我之前讲过catch这里再补充一个小细节如果项目里你在很多地方用 DataStore.data请务必定义一个顶层函数参数是FlowT返回FlowT内部完成 IOException 捕获和默认值替换然后用JvmName标注一下避免泛型擦除问题。这样哪怕你以后换文件、换存储实现这个防线都不会丢。第三个是慎用DataStore.data.first()。这个 API 很方便但它是“一次性读取当前值”不会持续监听。如果你在界面初始化时拿一次值进状态这个行为没问题但如果你打算拿完值后继续在某些回调里更新 UI请改用 collect。代码审查时我发现过好几次这种误用现象就是“设置页改了配置上一页的文案没变”。第四个是关于同步代码DataStore 是异步的你不应该也没有办法同步拿到其中的值。如果有人提 PR 里写runBlocking { dataStore.data.first() }务必让 TA 重新思考这种写法出现在主线程几乎等于自杀出现在后台线程则浪费了协程的优势。10. 从 SharedPreferences 平滑迁移的逐步清单如果你正好负责一个老项目的配置存储迁移我建议按这个顺序来踩坑概率低很多。第一步梳理现有 SharedPreferences 的 key 全集。包括 key 名、类型、默认值、使用方。做了这个清单你才敢开始动刀。第二步确定存储模式。根据前面章节的选型逻辑画出哪些 key 进哪个 DataStore 文件。第三步新建 DataStore 文件并写迁移逻辑。从 SharedPreferences 迁到 Preferences DataStore 直接用官方SharedPreferencesMigration如果需要加工数据结构比如把旧的多个 key 合并成新 key用自定义MigrationPreferences。第四步在 App 启动的前几个关键路径里做一次强制初始化触发迁移。常见的做法是在启动时调用一次dataStore.data.first()让迁移尽快发生。第五步逐模块替换业务代码。先替换读写最频繁的地方验证 UI 刷新、二次启动、进程杀掉重启这三关都通过后再继续换下一个模块。第六步灰度上线观察崩溃率和数据异常上报。Server 端统计如果有配置类字段建议前两周对比迁移前后数据量是否有减少。如果数据掉得厉害优先检查文件实例名是否改变了。这套流程走完迁移基本就稳了。我自己做第三个项目时踩着上面这些坑折腾了两三天后来梳理出这套流程再迁移新模块基本上半天能搞定一个。DataStore 说难不难说简单它又比 SharedPreferences 多了不少需要想清楚的设计点。只要你把文件实例、Key 类型、异常降级、职责分层这四件事理清楚日常开发里它会成为非常靠谱的基础设施。