DataStore

异步、一致且事务性地存储数据，克服 SharedPreferences 的一些缺点

最新更新	稳定版	发布候选版	Beta 版	Alpha 版
2025 年 5 月 20 日	1.1.7	-	-	1.2.0-alpha02

声明依赖项

要添加 DataStore 依赖项，您必须将 Google Maven 仓库添加到您的项目中。如需了解更多信息，请阅读Google 的 Maven 仓库。

DataStore 有两种实现：Preferences 和 Proto。请选择其中一种。您也可以为任一实现添加不依赖 Android 的依赖项。

在您的应用或模块的 build.gradle 文件中添加所需实现的依赖项

Preferences DataStore

Groovy

    // Preferences DataStore (SharedPreferences like APIs)
    dependencies {
        implementation "androidx.datastore:datastore-preferences:1.1.7"

        // optional - RxJava2 support
        implementation "androidx.datastore:datastore-preferences-rxjava2:1.1.7"

        // optional - RxJava3 support
        implementation "androidx.datastore:datastore-preferences-rxjava3:1.1.7"
    }

    // Alternatively - use the following artifact without an Android dependency.
    dependencies {
        implementation "androidx.datastore:datastore-preferences-core:1.1.7"
    }

Kotlin

    // Preferences DataStore (SharedPreferences like APIs)
    dependencies {
        implementation("androidx.datastore:datastore-preferences:1.1.7")

        // optional - RxJava2 support
        implementation("androidx.datastore:datastore-preferences-rxjava2:1.1.7")

        // optional - RxJava3 support
        implementation("androidx.datastore:datastore-preferences-rxjava3:1.1.7")
    }

    // Alternatively - use the following artifact without an Android dependency.
    dependencies {
        implementation("androidx.datastore:datastore-preferences-core:1.1.7")
    }

Proto DataStore

Groovy

    // Typed DataStore (Typed API surface, such as Proto)
    dependencies {
        implementation "androidx.datastore:datastore:1.1.7"

        // optional - RxJava2 support
        implementation "androidx.datastore:datastore-rxjava2:1.1.7"

        // optional - RxJava3 support
        implementation "androidx.datastore:datastore-rxjava3:1.1.7"
    }

    // Alternatively - use the following artifact without an Android dependency.
    dependencies {
        implementation "androidx.datastore:datastore-core:1.1.7"
    }

Kotlin

    // Typed DataStore (Typed API surface, such as Proto)
    dependencies {
        implementation("androidx.datastore:datastore:1.1.7")

        // optional - RxJava2 support
        implementation("androidx.datastore:datastore-rxjava2:1.1.7")

        // optional - RxJava3 support
        implementation("androidx.datastore:datastore-rxjava3:1.1.7")
    }

    // Alternatively - use the following artifact without an Android dependency.
    dependencies {
        implementation("androidx.datastore:datastore-core:1.1.7")
    }

反馈

您的反馈有助于改进 Jetpack。如果您发现新问题或有改进此库的想法，请告诉我们。在创建新问题之前，请先查看此库中的现有问题。您可以通过点击星形按钮为您关注的现有问题投票。

创建新问题

如需了解更多信息，请参阅问题跟踪器文档。

版本 1.2

版本 1.2.0-alpha02

2025 年 5 月 7 日

androidx.datastore:datastore-*:1.2.0-alpha02 已发布。版本 1.2.0-alpha02 包含这些提交。

API 变更

在 GuavaDataStore 中添加了多进程支持。（e0d608a）。
添加了一个辅助方法，用于从 DataStore 创建 GuavaDataStore。（9af26f4）
使用 Kotlin 2.0 发布的项目需要使用 KGP 2.0.0 或更高版本。（Idb6b5）
将现有的 datastore 重载替换为委托方法，以初始化在直接启动期间使用的 DataStore。（If71b9）

版本 1.2.0-alpha01

2025 年 3 月 26 日

androidx.datastore:datastore-*:1.2.0-alpha01 已发布。版本 1.2.0-alpha01 包含这些提交。

新功能

添加了 datastore-guava 模块，通过 GuavaDataStore 向 Java 和 Guava ListenableFuture 用户公开友好的 API。（Iadd5e0）
现在支持在 DirectBoot 模式下使用 DataStore。要在直接启动模式下创建数据存储，必须在设备保护存储中创建。这可以通过以下新的 DataStore API 实现：`DataStoreFactory` 中的 createInDeviceProtectedStorage() 和 DataStoreDelegate 中的 deviceProtectedDataStore()。（Ib90e56）

API 变更

添加了 PreferencesFileSerializer，它实现了 androidx.datastore.core.Serializer 接口，可与 FileStorage 配合使用。（I4c71f3）

Bug 修复

通过在竞争条件下添加第二次尝试读取数据，解决了 OkioStorage 在启动时出现的 FileNotFoundException 问题。（I43b3fb、b/337870543）
为 ReplaceFileCorruptionHandler 定义了默认构造函数，以便通用代码使用。（I795b05、b/358138957）

版本 1.1

版本 1.1.7

2025 年 5 月 20 日

androidx.datastore:datastore-*:1.1.7 已发布。版本 1.1.7 包含这些提交。

Bug 修复

修复了 datastore-preferences-core 的 Android 工件中 Proguard 规则缺失的问题。（3f3f6e、b/413078297）

版本 1.1.6

2025 年 5 月 7 日

androidx.datastore:datastore-*:1.1.6 已发布。版本 1.1.6 包含这些提交。

Bug 修复

解决了 1.1.5 版本中 Gradle 元数据损坏的问题。此问题是由于新的 AGP KMP 插件 DSL 中的一个错误导致的，该错误阻止了所有目标平台的元数据自动包含。该错误导致某些 DataStore Android 方法在客户端构建中不再可见。修复方法是在 build.gradle 中使用旧的 android DSL 而不是 androidLibrary。（7801abf）

版本 1.1.5

2025 年 4 月 23 日

androidx.datastore:datastore-*:1.1.5 已发布。版本 1.1.5 包含这些提交。

Bug 修复

为了缓解 PreferencesDataStore 中的 CorruptionException 问题，默认存储已从 OkioStorage 更改为 FileStorage。此更改通过引入 PreferencesFileSerializer 来实现。b/346197747

版本 1.1.4

2025 年 3 月 26 日

androidx.datastore:datastore-*:1.1.4 已发布。版本 1.1.4 包含这些提交。

Bug 修复

将默认存储从 OkioStorage 替换为 FileStorage，以通过减少 CorruptionException 来提高可靠性。（I71181、b/346197747）

版本 1.1.3

2025 年 2 月 26 日

androidx.datastore:datastore-*:1.1.3 已发布。版本 1.1.3 包含这些提交。

Bug 修复

解决了应用启动时 OkioStorage 中遇到的 FileNotFoundException 问题。如果初始文件读取尝试失败，则会在发生竞争条件（由于文件在初始读取期间由其他进程创建）的情况下进行第二次尝试。（I43b3f、b/337870543）

版本 1.1.2

2025 年 1 月 15 日

androidx.datastore:datastore-*:1.1.2 已发布。版本 1.1.2 包含这些提交。

Bug 修复

将热读取延迟 (DataStore.data.first()) 提高 8 倍。（22b8a40）
ReplaceFileCorruptionHandler 可以从 KMP 公共代码中创建。（7632e839）

版本 1.1.1

2024 年 5 月 1 日

androidx.datastore:datastore-*:1.1.1 已发布。版本 1.1.1 包含这些提交。

Bug 修复

缓解了 Linux 在极端情况下报告的“资源死锁”错误假警报，即当多个 DataStore 实例尝试从不同进程写入时，通过回退文件锁来解决。

版本 1.1.0

2024 年 4 月 17 日

androidx.datastore:datastore-*:1.1.0 已发布。版本 1.1.0 包含这些提交。

自 1.0.0 版本以来的主要变更

请查阅 1.1.0 的 Alpha 和 Beta 版本的版本说明以获取更多信息。1.1.0 中的一些主要更新包括：

DataStore 现在支持多个进程访问同一文件，并支持跨进程的可观察性。
新的 Storage 接口允许您自定义如何存储或序列化数据模型。
您现在可以在 Kotlin 多平台项目中使用 DataStore。

版本 1.1.0-rc01

2024 年 4 月 3 日

androidx.datastore:datastore-*:1.1.0-rc01 已发布。版本 1.1.0-rc01 包含这些提交。

Bug 修复

修复了性能下降问题，即当新数据与旧数据相同时，updateData 调用不会优化磁盘写入（d64cfb5）
修复了多进程 DataStore 在初始化期间可能遗漏失效通知的竞争条件。（(b/326141553)、(094c2dd)）

版本 1.1.0-beta02

2024 年 3 月 6 日

androidx.datastore:datastore-*:1.1.0-beta02 已发布。版本 1.1.0-beta02 包含这些提交。

Bug 修复

DataStore 性能改进：仅当被观察时才收集更新通知。（b/267792241）
- 请注意，如果您使用 Coroutines 测试库，此更改可能会在您的测试中触发 UncompletedCoroutinesError。请确保在测试中初始化 DataStore 时传入 TestScope.backgroundScope 以避免此问题。
修复了同一实例上嵌套的 updateData 调用会导致死锁的问题。（b/241760537）
修复了 DataStore 在迁移过程中删除 SharedPreferences 失败时不再抛出 IOException 的问题。（b/195553816）
修复了在非 Android JVM 环境中 updateData 期间文件重命名失败的问题。（b/203087070）
修复了 DataStore 初始化后未处理 CorruptionException 的问题。（b/289582516）

版本 1.1.0-beta01

2024 年 1 月 10 日

androidx.datastore:datastore-*:1.1.0-beta01 已发布，自 1.1.0-alpha07 以来无变化。版本 1.1.0-beta01 包含这些提交。

版本 1.1.0-alpha07

2023 年 11 月 29 日

androidx.datastore:datastore-*:1.1.0-alpha07 已发布。版本 1.1.0-alpha07 包含这些提交。

API 变更

MultiProcessDataStoreFactory 方法不再是实验性功能。@ExperimentalMultiProcessDataStore 注解已完全移除。（Ieee54、I8e607）

Bug 修复

将 @ExperimentalMultiProcessDataStore 注解的移除推广到 1.1.0-alpha07。（I8e607）

版本 1.1.0-alpha06

2023 年 11 月 1 日

androidx.datastore:datastore-*:1.1.0-alpha06 已发布。版本 1.1.0-alpha06 包含这些提交。

API 变更

createSingleProcessCoordinator 工厂方法现在接收文件路径（String、java.io.File 和 okio.Path），以与 createMultiProcessCoordinator 保持一致。（I211c8、b/305755935）

版本 1.1.0-alpha05

2023 年 9 月 6 日

androidx.datastore:datastore-*:1.1.0-alpha05 已发布。版本 1.1.0-alpha05 包含这些提交。

API 变更

Datastore 的 FileStorage 现在已公开可用，因此客户端可以提供自定义参数。（Icb985）
更改了 OkioStorage 构造函数以接受 InterProcessCoordinator，使其可以在 Android 上与 MultiProcessCoordinator 一起使用。（Iecea3）

Bug 修复

修复了 MultiProcessCoordinator 无法监控同一目录中多个文件的问题。
修复了如果文件路径未规范化则无法检测重复文件的问题。
修复了 RxDataStore#isDisposed 返回错误值的问题。
修复了 datstore-preferences-core 工件缺少 proguard 配置的问题。

版本 1.1.0-alpha04

2023 年 4 月 5 日

androidx.datastore:datastore-*:1.1.0-alpha04 已发布。版本 1.1.0-alpha04 包含这些提交。

Bug 修复

改进内部实现，以避免在更新后 DataStore 的数据流可能发出旧值的竞争条件。

版本 1.1.0-alpha03

2023 年 3 月 24 日

androidx.datastore:datastore-*:1.1.0-alpha03 已发布。

Bug 修复

移除了 Maven 工件的依赖项约束，以解决 Kotlin Native 目标中的构建问题（b/274786186、KT-57531）。

版本 1.1.0-alpha02

2023 年 3 月 22 日

androidx.datastore:datastore-*:1.1.0-alpha02 已发布。版本 1.1.0-alpha02 包含这些提交。

注意

请注意，此版本包含一项重要的内部重构，它合并了单进程和多进程 DataStore 实现。请留意可能出现的意外行为更改（例如更新通知的时机）。您可以使用问题跟踪器组件报告此类更改。

新功能

您现在可以在 KMM 项目中使用 DataStore。请注意，DataStore 的非 Android 目标仍处于实验阶段，但我们决定合并版本，以便开发人员更容易尝试。
多进程功能已从 androidx.datastore.multiprocess 移至 androidx.datastore.core。
在 androidx.datastore.core.MultiProcessDataStoreFactory 中添加了一个新的工厂方法，用于创建使用 Storage 对象进行文件操作的 DataStore 实例。
添加了一个新的接口 InterProcessCoordinator，它有助于多个 DataStore 实例之间进行跨进程通信。请注意，InterProcessCoordinator 的多进程实现仅在 Android 上可用。

API 变更

在 datastore-core 接口中的 StorageConnection 中添加 InterProcessCoordinator（I555bb）
更改 datastore-core 中的 MultiProcessDataStoreFactory API 以使用 Storage。（Iac02f）
将 datastore-multiprocess 中的公共 API 移至 datastore-core（I76d7c）
从 datastore-preferences-core 公开 PreferencesSerializer（I4b788）
添加 @JvmDefaultWithCompatibility 注解（I8f206）

版本 1.1.0-alpha01

2022 年 11 月 9 日

androidx.datastore:datastore-*:1.1.0-alpha01 已发布。版本 1.1.0-alpha01 包含这些提交。

新功能

支持多进程用例，其中跨进程的 DataStore 实例之间的数据一致性得到保证。添加 MultiProcessDataStoreFactory#create 以创建此类 DataStore 实例。
新的 Storage 接口允许更换 Datastore 的底层存储机制。提供了 java.io 和 okio 的实现。DataStore 工厂有新的方法接受此 Storage 对象。

API 变更

更改 datastore-core 中的 MultiProcessDataStoreFactory API 以使用 Storage。（Iac02f）
将 datastore-multiprocess 中的公共 API 移至 datastore-core（I76d7c）
从 datastore-preferences-core 公开 PreferencesSerializer（I4b788）

版本 1.0.0

2021 年 8 月 4 日

androidx.datastore:datastore-*:1.0.0 已发布。版本 1.0.0 包含这些提交。

1.0.0 的主要功能

Jetpack DataStore 是一种数据存储解决方案，允许您使用协议缓冲区存储键值对或类型化对象。DataStore 使用 Kotlin 协程和 Flow 异步、一致且事务性地存储数据。

版本 1.0.0-rc02

2021 年 7 月 21 日

androidx.datastore:datastore-*:1.0.0-rc02 已发布。版本 1.0.0-rc02 包含这些提交。

Bug 修复

澄清如果不存在任何键，SharedPreferencesMigration 将不会运行。（Icfa32、b/192824325）
修复了使用 MIGRATE_ALL_KEYS 构建的 SharedPreferencesMigration 在请求的键尚不存在时会抛出异常的错误。（Ie318a、b/192824325）

版本 1.0.0-rc01

2021 年 6 月 30 日

androidx.datastore:datastore-*:1.0.0-rc01 已发布。版本 1.0.0-rc01 包含这些提交。

Bug 修复

修复了 .java 文件意外添加到最终 jar 包中的错误（I65d96、b/188985637）

版本 1.0.0-beta02

2021 年 6 月 16 日

androidx.datastore:datastore-*:1.0.0-beta02 已发布。版本 1.0.0-beta02 包含这些提交。

Bug 修复

修复 ClassVerificationFailure（b/187450483）

版本 1.0.0-beta01

2021 年 4 月 21 日

androidx.datastore:datastore-*:1.0.0-beta01 已发布。版本 1.0.0-beta01 包含这些提交。

API 变更

移除仅限 Kotlin 方法的 JVM 重载（I2adc7）

Bug 修复

修复了 datastore 委托可能导致上下文泄漏的错误（Ie96fc、b/184415662）

版本 1.0.0-alpha08

2021 年 3 月 10 日

androidx.datastore:datastore-*:1.0.0-alpha08 已发布。版本 1.0.0-alpha08 包含这些提交。

API 变更

您现在可以向 dataStore 和 preferencesDataStore 属性委托添加依赖于上下文的迁移。（I4ef69、b/173726702）
如果您不再使用 datastore 委托或 context.createDataStore，则添加用于获取文件名称的辅助函数。（I60f9a）
Serializer 的 writeTo 和 readFrom 现在是挂起函数。如果您已实现 `Serializer`，则需要将您的函数更新为挂起函数。（I1e58e）
为 RxDataStore 用户添加了属性委托。（Ied768、b/173726702）

Bug 修复

对实验性 API 的公共使用强制执行限制（I6aa29、b/174531520）

版本 1.0.0-alpha07

2021 年 2 月 24 日

androidx.datastore:datastore-*:1.0.0-alpha07 已发布。版本 1.0.0-alpha07 包含这些提交。

API 变更

Context.createDataStore 扩展函数已被移除，并替换为 globalDataStore 属性委托。在 Kotlin 文件中，您只需在顶级位置调用一次 globalDataStore。例如
```
val Context.myDataStore by dataStore(...)
```
将此代码放在您的 Kotlin 文件顶部，以确保只有一个实例。（I57215、b/173726702）
RxDataStore 函数现在位于 RxDataStore 类上，而不是 DataStore 的扩展函数。（Idccdb、b/177691248）
如果您想将 EncryptedSharedPreferences（或直接启动 SharedPreferences）迁移到 DataStore，您现在可以使用新的 SharedPreferencesMigration 构造函数，该构造函数允许您注入 SharedPreferences。（I8e04e、b/177278510）

Bug 修复

如果同一文件有多个活跃的 DataStore 实例，DataStore 现在将抛出异常。如果您没有将 DataStore 作为单例管理，或者没有确保同一文件没有两个 DataStore 实例同时活跃，那么您现在在读取或写入 DataStore 时可能会看到异常。这可以通过将 DataStore 作为单例管理来修复。（Ib43f4、b/177691248）
修复了当调用者作用域取消时取消行为的问题。（I2c7b3）

版本 1.0.0-alpha06

2021 年 1 月 13 日

androidx.datastore:datastore-*:1.0.0-alpha06 已发布。版本 1.0.0-alpha06 包含这些提交。

新功能

为 DataStore 添加了 RxJava 封装器。datastore-rxjava2/3 工件包含核心 DataStore API（RxDataStore、RxDataStoreBuilder 和 RxDataMigration）的封装器。datastore-preferences-rxjava2/3 工件包含用于构建 Preferences DataStore 的构建器。

API 变更

隐藏 CorruptionHandler 接口。它没有理由公开，因为 DataStore 工厂只接受 ReplaceFileCorruptionHandler。（I0b3b3、b/176032264）
preferencesKey<T>(name: String): Key<T> 方法已被移除，并替换为每种支持类型特定的方法，例如 preferencesKey<Int>("int") 现在是 intPreferencesKey("int")（Ibcfac、b/170311106）

Bug 修复

修复了 DataStoreFactory 文档中遗漏了 datastore 文件在“datastore/”子目录中创建的事实。（Ica222）

版本 1.0.0-alpha05

2020 年 12 月 2 日

androidx.datastore:datastore-*:1.0.0-alpha05 已发布。版本 1.0.0-alpha05 包含这些提交。

Bug 修复

增加了关于来自数据存储的并发写入的更好文档和异常。（Ia98a2、b/173522155、b/173726702）
我们现在允许（但不要求）关闭传递给 Serializer.writeTo() 的 OutputStream。（I5c9bf、b/173037611）

版本 1.0.0-alpha04

2020 年 11 月 17 日

androidx.datastore:datastore-*:1.0.0-alpha04 已发布。版本 1.0.0-alpha04 包含这些提交。

Bug 修复

修复了一个打包问题，该问题导致 Preference Datastore 1.0.0-alpha03 中出现以下崩溃：java.lang.NoClassDefFoundError: Failed resolution of: Landroidx/datastore/preferences
- 该崩溃最初在此处报告：b/173036843
- （I4712d、b/173036843）

版本 1.0.0-alpha03

2020 年 11 月 11 日

androidx.datastore:datastore-*:1.0.0-alpha03 已发布。版本 1.0.0-alpha03 包含这些提交。

注意： 请改用 1.0.0-alpha04 版本。在 1.0.0-alpha03 中发现了一个严重问题，导致 Preference Datastore 崩溃并出现 java.lang.NoClassDefFoundError。（b/173036843）

新功能

Preferences 现在支持双精度浮点值（如果您需要比浮点数更高的精度，这会很有用）（I5be8f、b/169471808）

API 变更

为 datastore 创建了纯 Kotlin 依赖项，以加快编译速度。androidx.datastore:datastore-core 包含核心仅 Kotlin API，androidx.datastore:datastore 包含依赖于 Android 的 API（包括 SharedPreferencesMigration 和 Context.createDataStore 构造函数）。（I42d75、b/168512698）
拆分 preferences data store 的目标以加快 Kotlin 编译（Ia3c19）
序列化器现在需要一个新属性来指定磁盘上没有数据时将使用的默认值。这使得实现自定义序列化器变得更容易，因此用户不必对空输入流进行特殊处理（空输入流无法用 json 解析）。
- 此外，现在有一个检查，以确认提供给 writeTo() 的输出流未关闭，如果已关闭，则会抛出异常（I16e29）
将 SharedPreferencesView 的构造函数设置为内部。它最初是公开的，以允许测试。测试应改为构造 SharedPreferencesMigration 并对其进行测试。（I93891）

Bug 修复

DataStoreFactory 和 PreferenceDataStoreFactory 上的 produceFile 参数现在是列表中的最后一个参数，因此它允许您使用 Kotlin 尾随 lambda 语法。（Ibe7f1、b/169425442）
遵循 Kotlin 的新显式 API 要求（I5ae1e）

已知问题

Preference Datastore 崩溃并出现 java.lang.NoClassDefFoundError。（b/173036843）

版本 1.0.0-alpha02

2020 年 10 月 14 日

androidx.datastore:datastore-core:1.0.0-alpha02 和 androidx.datastore:datastore-preferences:1.0.0-alpha02 已发布。版本 1.0.0-alpha02 包含这些提交。

Bug 修复

在 datastore-core 中添加了针对变异的保护。变异会破坏使用非 proto/非 preferences 类型的 datastore 的用户对 datastore 的使用。（I6aa84）
在 Preferences.kt 中添加了 toString 方法，以便轻松调试当前状态。（I96006）
添加了一个异常以防止误用 DataStore.Preferences。（I1134d）
修复了一个会导致应用在启动时崩溃的错误。（I69237、b/168580258）

版本 1.0.0-alpha01

2020 年 9 月 2 日

androidx.datastore:datastore-core:1.0.0-alpha01 和 androidx.datastore:datastore-preferences:1.0.0-alpha01 已发布。版本 1.0.0-alpha01 包含这些提交。

新功能

Jetpack DataStore 是一种新的改进型数据存储解决方案，旨在取代 SharedPreferences。DataStore 基于 Kotlin 协程和 Flow 构建，提供两种不同的实现：

Proto DataStore，允许您存储类型化对象（由协议缓冲区支持）
Preferences DataStore，存储键值对

数据以异步、一致和事务性的方式存储，克服了 SharedPreferences 的大部分缺点。