Flutter Windows 平台持久化存储实战shared_preferences_windows 联邦插件实现与使用指南【免费下载链接】packagesA collection of useful packages maintained by the Flutter team项目地址: https://gitcode.com/GitHub_Trending/pac/packagesshared_preferences_windows是 Flutter 官方维护的shared_preferences联邦插件Federated Plugin在 Windows 平台的实现负责把键值对数据以 JSON 文件形式持久化到 Windows 应用支持目录。本指南将围绕该包的背书endorsed使用机制、源码级存储原理、新旧两套 API 的差异以及前缀过滤等高级能力展开帮助开发者在 Windows 桌面应用中选择正确的接入方式并理解数据落盘细节。一、包定位Windows 实现与背书endorsed机制shared_preferences采用联邦插件架构面向应用的是统一 API 入口包面向各平台的是各自的实现包。shared_preferences_windows正是其中的 Windows 实现其官方定位为 The Windows implementation ofshared_preferences对应源码位于 packages/shared_preferences/shared_preferences_windows/lib/shared_preferences_windows.dart。该包在 pubspec.yaml 中通过flutter.plugin.implements: shared_preferences声明自己实现了shared_preferences的接口并在platforms.windows下注册了dartPluginClass: SharedPreferencesWindowsname: shared_preferences_windows version: 2.4.1 environment: sdk: ^3.10.0 flutter: 3.38.0 flutter: plugin: implements: shared_preferences platforms: windows: dartPluginClass: SharedPreferencesWindows dependencies: file: 6.0.0 8.0.0 path: ^1.8.0 path_provider_platform_interface: ^2.0.0 path_provider_windows: ^2.0.0 shared_preferences_platform_interface: ^2.4.0从依赖关系可以看出该实现并不直接操作 Windows 注册表或原生 API而是依赖path_provider_windows定位应用支持目录依赖file与path完成文件读写属于纯 Dart 实现dartPluginClass而非原生 pluginClass。背书机制为什么你不用手动添加它原文档强调这个包是endorsed被背书的当你正常使用shared_preferences时本包会被自动带入项目无需在pubspec.yaml中显式添加shared_preferences_windows。这是联邦插件中实现包被入口包认可的标准机制也是该包 README 的核心结论。唯一需要显式声明依赖的场景是如果你要import package:shared_preferences_windows/shared_preferences_windows.dart并直接使用其内部 API例如构造SharedPreferencesAsyncWindows并传入自定义SharedPreferencesWindowsOptions此时按惯例应把它加入pubspec.yaml的 dependencies 中。二、接入与使用普通用法零配置对绝大多数应用而言接入方式与使用其他平台完全相同——只需依赖应用侧包shared_preferencesWindows 数据持久化能力即自动生效。支持的存储类型为int、double、bool、String与ListString。应用侧经典用法参见 shared_preferences 主包 README// 写入 final SharedPreferences prefs await SharedPreferences.getInstance(); await prefs.setInt(counter, 10); await prefs.setBool(repeat, true); await prefs.setDouble(decimal, 1.5); await prefs.setString(action, Start); await prefs.setStringList(items, String[Earth, Moon, Sun]); // 读取键不存在时返回 null final int? counter prefs.getInt(counter); final ListString? items prefs.getStringList(items); // 删除 await prefs.remove(counter);从版本 2.3.0 起shared_preferences提供了三套 APISharedPreferences遗留 API未来将弃用、SharedPreferencesAsync与SharedPreferencesWithCache。官方强烈建议新用户使用后两者Windows 实现同样分别提供了对应的底层支持类详见下文第三节。三、源码级原理数据如何落到 Windows 磁盘存储位置与文件格式shared_preferences_windows的核心是把整个偏好字典序列化为单个 JSON 文件。文件路径由_getLocalDataFile决定源码第 270-282 行final String? directory await pathProvider.getApplicationSupportPath(); final String fileLocation path.join(directory, $fileName.json); return fs.file(fileLocation);即使用PathProviderWindows.getApplicationSupportPath()得到应用支持目录再拼上shared_preferences.json默认文件名常量_defaultFileName shared_preferences位于源码第 17 行。读取时若文件不存在或为空则返回空 Map写入时若文件不存在会createSync(recursive: true)自动创建源码第 304-332 行。读写都是同步文件操作值得注意的实现事实尽管 API 是异步的Future返回但底层的readAsStringSync、writeAsStringSync均为同步文件 I/O源码第 285-332 行再套上json.encode/json.decode完成序列化。因此在 Windows 上每次读写都会真实触碰磁盘且写入失败如无法确定目录时会通过debugPrint打印诊断信息并返回false。内存缓存与数据一致性两个实现类内部都有MapString, Object? _cachedPreferences作为本地缓存首次访问时从文件加载并缓存之后所有读写都直接基于缓存进行每次setValue/remove/clear操作都会把整个缓存重新写回文件。这也意味着跨 isolate 使用时每个 isolate 拥有独立单例与独立缓存可能读到过期数据若在插件之外直接修改了磁盘上的 JSON 文件缓存不会自动感知需要时可在应用侧调用reload()强制重新从文件加载SharedPreferencesAsyncWindows通过visibleForTesting暴露了reload方法见源码第 231-235 行。四、两套 API 的实现Store 平台类与 Async 平台类遗留 APISharedPreferencesWindowsSharedPreferencesWindows继承SharedPreferencesStorePlatform为SharedPreferences与SharedPreferencesWithCache提供底层存储能力。它的registerWith()除了注册自身还会顺带注册SharedPreferencesAsyncWindows源码注释说明这是两个插件共存于同一包的临时兼容措施见源码第 31-35 行。该类实现的接口方法包括方法行为getAll()读取全部偏好但只返回带默认前缀flutter.的键getAllWithPrefix(prefix)返回指定前缀的键值对getAllWithParameters(...)支持前缀 allowList 组合过滤setValue(type, key, value)写入单条数据remove(key)删除单条数据clear()/clearWithPrefix()/clearWithParameters()按前缀/白名单清空其中PreferencesFilter的过滤逻辑在 clearWithParameters 与 getAllWithParameters 中体现键必须startsWith(prefix)且当allowList非空时包含于allowList。默认前缀常量为flutter.源码第 19 行这解释了为什么getAll()只能看到应用侧写入的键。新 APISharedPreferencesAsyncWindowsSharedPreferencesAsyncWindows声明为base class继承SharedPreferencesAsyncPlatform是为SharedPreferencesAsync提供支撑的无缓存实现提供getString/getBool/getInt/getDouble/getStringList/setString/.../getKeys/getPreferences/clear等完整方法并通过SharedPreferencesWindowsOptions支持自定义存储文件名源码第 335-353 行class SharedPreferencesWindowsOptions extends SharedPreferencesOptions { const SharedPreferencesWindowsOptions({ this.fileName shared_preferences, // 默认文件名 }); final String fileName; }应用侧如需把数据写入独立文件可在使用SharedPreferencesAsync时传入该选项。注意fromSharedPreferencesOptions会做类型判断如果传入的不是SharedPreferencesWindowsOptions则回退到默认文件名源码第 346-353 行。五、测试佐证可验证的实现行为仓库内两个测试文件完整覆盖了上述行为可以作为理解实现细节的活文档legacy_shared_preferences_windows_test.dart验证SharedPreferencesWindows的getAll只返回flutter.前缀键、getAllWithPrefix、clearWithPrefix、setValue、remove等行为并直接断言落盘 JSON 内容例如setValue后文件内容为{key1:one,key2:2}shared_preferences_windows_async_test.dart验证SharedPreferencesAsyncWindows五种数据类型的 set/get 往返、getPreferences/getKeys的allowList过滤以及clear含带过滤器的部分清除。测试通过 fake_path_provider_windows.dart 把getApplicationSupportPath()固定为C:\appsupport再配合MemoryFileSystem在任意机器上无副作用地验证文件读写逻辑——这也侧面印证了路径解析 JSON 文件读写是该实现的全部存储机制。六、适用前提与注意事项版本与环境当前包版本 2.4.1要求 Dart SDK^3.10.0、Flutter3.38.0见 pubspec.yaml请确认你的项目环境满足约束。数据可靠性主包 README 明确提示数据是异步落盘的不能用于存储关键数据Windows 实现虽然底层为同步文件写入但应用侧仍应遵循这一原则。缓存一致性多 isolate 或多引擎实例场景下缓存可能导致读到旧值若此类场景频繁优先使用无缓存的SharedPreferencesAsync。调试提示实际调试时可在 Windows 应用支持目录下直接查看/编辑shared_preferences.json文件以核对数据。示例工程仓库中的 example 是平台实现的集成测试 App含windows/桌面工程骨架并非面向最终用户的用法演示普通应用只需依赖应用侧包即可。七、总结shared_preferences_windows通过联邦插件的背书机制让 Windows 开发者无需任何额外配置即可获得键值持久化能力。其实现本质是应用支持目录下的 JSON 文件 内存缓存同时为遗留SharedPreferences与新SharedPreferencesAsync两套 API 分别提供了平台实现并支持前缀过滤与自定义文件名等进阶能力。理解这些源码细节有助于在 Windows 桌面应用开发中正确评估数据一致性、选择合适 API并快速定位存储相关的疑难问题。【免费下载链接】packagesA collection of useful packages maintained by the Flutter team项目地址: https://gitcode.com/GitHub_Trending/pac/packages创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 
长河君 · 2026/9/19 4:12:18 · 阅读 1.2k Flutter Windows 平台持久化存储实战：shared_preferences_windows 联邦插件实现与使用指南
Flutter Windows 平台持久化存储实战shared_preferences_windows 联邦插件实现与使用指南【免费下载链接】packagesA collection of useful packages maintained by the Flutter team项目地址: https://gitcode.com/GitHub_Trending/pac/packagesshared_preferences_windows是 Flutter 官方维护的shared_preferences联邦插件Federated Plugin在 Windows 平台的实现负责把键值对数据以 JSON 文件形式持久化到 Windows 应用支持目录。本指南将围绕该包的背书endorsed使用机制、源码级存储原理、新旧两套 API 的差异以及前缀过滤等高级能力展开帮助开发者在 Windows 桌面应用中选择正确的接入方式并理解数据落盘细节。一、包定位Windows 实现与背书endorsed机制shared_preferences采用联邦插件架构面向应用的是统一 API 入口包面向各平台的是各自的实现包。shared_preferences_windows正是其中的 Windows 实现其官方定位为 The Windows implementation ofshared_preferences对应源码位于 packages/shared_preferences/shared_preferences_windows/lib/shared_preferences_windows.dart。该包在 pubspec.yaml 中通过flutter.plugin.implements: shared_preferences声明自己实现了shared_preferences的接口并在platforms.windows下注册了dartPluginClass: SharedPreferencesWindowsname: shared_preferences_windows version: 2.4.1 environment: sdk: ^3.10.0 flutter: 3.38.0 flutter: plugin: implements: shared_preferences platforms: windows: dartPluginClass: SharedPreferencesWindows dependencies: file: 6.0.0 8.0.0 path: ^1.8.0 path_provider_platform_interface: ^2.0.0 path_provider_windows: ^2.0.0 shared_preferences_platform_interface: ^2.4.0从依赖关系可以看出该实现并不直接操作 Windows 注册表或原生 API而是依赖path_provider_windows定位应用支持目录依赖file与path完成文件读写属于纯 Dart 实现dartPluginClass而非原生 pluginClass。背书机制为什么你不用手动添加它原文档强调这个包是endorsed被背书的当你正常使用shared_preferences时本包会被自动带入项目无需在pubspec.yaml中显式添加shared_preferences_windows。这是联邦插件中实现包被入口包认可的标准机制也是该包 README 的核心结论。唯一需要显式声明依赖的场景是如果你要import package:shared_preferences_windows/shared_preferences_windows.dart并直接使用其内部 API例如构造SharedPreferencesAsyncWindows并传入自定义SharedPreferencesWindowsOptions此时按惯例应把它加入pubspec.yaml的 dependencies 中。二、接入与使用普通用法零配置对绝大多数应用而言接入方式与使用其他平台完全相同——只需依赖应用侧包shared_preferencesWindows 数据持久化能力即自动生效。支持的存储类型为int、double、bool、String与ListString。应用侧经典用法参见 shared_preferences 主包 README// 写入 final SharedPreferences prefs await SharedPreferences.getInstance(); await prefs.setInt(counter, 10); await prefs.setBool(repeat, true); await prefs.setDouble(decimal, 1.5); await prefs.setString(action, Start); await prefs.setStringList(items, String[Earth, Moon, Sun]); // 读取键不存在时返回 null final int? counter prefs.getInt(counter); final ListString? items prefs.getStringList(items); // 删除 await prefs.remove(counter);从版本 2.3.0 起shared_preferences提供了三套 APISharedPreferences遗留 API未来将弃用、SharedPreferencesAsync与SharedPreferencesWithCache。官方强烈建议新用户使用后两者Windows 实现同样分别提供了对应的底层支持类详见下文第三节。三、源码级原理数据如何落到 Windows 磁盘存储位置与文件格式shared_preferences_windows的核心是把整个偏好字典序列化为单个 JSON 文件。文件路径由_getLocalDataFile决定源码第 270-282 行final String? directory await pathProvider.getApplicationSupportPath(); final String fileLocation path.join(directory, $fileName.json); return fs.file(fileLocation);即使用PathProviderWindows.getApplicationSupportPath()得到应用支持目录再拼上shared_preferences.json默认文件名常量_defaultFileName shared_preferences位于源码第 17 行。读取时若文件不存在或为空则返回空 Map写入时若文件不存在会createSync(recursive: true)自动创建源码第 304-332 行。读写都是同步文件操作值得注意的实现事实尽管 API 是异步的Future返回但底层的readAsStringSync、writeAsStringSync均为同步文件 I/O源码第 285-332 行再套上json.encode/json.decode完成序列化。因此在 Windows 上每次读写都会真实触碰磁盘且写入失败如无法确定目录时会通过debugPrint打印诊断信息并返回false。内存缓存与数据一致性两个实现类内部都有MapString, Object? _cachedPreferences作为本地缓存首次访问时从文件加载并缓存之后所有读写都直接基于缓存进行每次setValue/remove/clear操作都会把整个缓存重新写回文件。这也意味着跨 isolate 使用时每个 isolate 拥有独立单例与独立缓存可能读到过期数据若在插件之外直接修改了磁盘上的 JSON 文件缓存不会自动感知需要时可在应用侧调用reload()强制重新从文件加载SharedPreferencesAsyncWindows通过visibleForTesting暴露了reload方法见源码第 231-235 行。四、两套 API 的实现Store 平台类与 Async 平台类遗留 APISharedPreferencesWindowsSharedPreferencesWindows继承SharedPreferencesStorePlatform为SharedPreferences与SharedPreferencesWithCache提供底层存储能力。它的registerWith()除了注册自身还会顺带注册SharedPreferencesAsyncWindows源码注释说明这是两个插件共存于同一包的临时兼容措施见源码第 31-35 行。该类实现的接口方法包括方法行为getAll()读取全部偏好但只返回带默认前缀flutter.的键getAllWithPrefix(prefix)返回指定前缀的键值对getAllWithParameters(...)支持前缀 allowList 组合过滤setValue(type, key, value)写入单条数据remove(key)删除单条数据clear()/clearWithPrefix()/clearWithParameters()按前缀/白名单清空其中PreferencesFilter的过滤逻辑在 clearWithParameters 与 getAllWithParameters 中体现键必须startsWith(prefix)且当allowList非空时包含于allowList。默认前缀常量为flutter.源码第 19 行这解释了为什么getAll()只能看到应用侧写入的键。新 APISharedPreferencesAsyncWindowsSharedPreferencesAsyncWindows声明为base class继承SharedPreferencesAsyncPlatform是为SharedPreferencesAsync提供支撑的无缓存实现提供getString/getBool/getInt/getDouble/getStringList/setString/.../getKeys/getPreferences/clear等完整方法并通过SharedPreferencesWindowsOptions支持自定义存储文件名源码第 335-353 行class SharedPreferencesWindowsOptions extends SharedPreferencesOptions { const SharedPreferencesWindowsOptions({ this.fileName shared_preferences, // 默认文件名 }); final String fileName; }应用侧如需把数据写入独立文件可在使用SharedPreferencesAsync时传入该选项。注意fromSharedPreferencesOptions会做类型判断如果传入的不是SharedPreferencesWindowsOptions则回退到默认文件名源码第 346-353 行。五、测试佐证可验证的实现行为仓库内两个测试文件完整覆盖了上述行为可以作为理解实现细节的活文档legacy_shared_preferences_windows_test.dart验证SharedPreferencesWindows的getAll只返回flutter.前缀键、getAllWithPrefix、clearWithPrefix、setValue、remove等行为并直接断言落盘 JSON 内容例如setValue后文件内容为{key1:one,key2:2}shared_preferences_windows_async_test.dart验证SharedPreferencesAsyncWindows五种数据类型的 set/get 往返、getPreferences/getKeys的allowList过滤以及clear含带过滤器的部分清除。测试通过 fake_path_provider_windows.dart 把getApplicationSupportPath()固定为C:\appsupport再配合MemoryFileSystem在任意机器上无副作用地验证文件读写逻辑——这也侧面印证了路径解析 JSON 文件读写是该实现的全部存储机制。六、适用前提与注意事项版本与环境当前包版本 2.4.1要求 Dart SDK^3.10.0、Flutter3.38.0见 pubspec.yaml请确认你的项目环境满足约束。数据可靠性主包 README 明确提示数据是异步落盘的不能用于存储关键数据Windows 实现虽然底层为同步文件写入但应用侧仍应遵循这一原则。缓存一致性多 isolate 或多引擎实例场景下缓存可能导致读到旧值若此类场景频繁优先使用无缓存的SharedPreferencesAsync。调试提示实际调试时可在 Windows 应用支持目录下直接查看/编辑shared_preferences.json文件以核对数据。示例工程仓库中的 example 是平台实现的集成测试 App含windows/桌面工程骨架并非面向最终用户的用法演示普通应用只需依赖应用侧包即可。七、总结shared_preferences_windows通过联邦插件的背书机制让 Windows 开发者无需任何额外配置即可获得键值持久化能力。其实现本质是应用支持目录下的 JSON 文件 内存缓存同时为遗留SharedPreferences与新SharedPreferencesAsync两套 API 分别提供了平台实现并支持前缀过滤与自定义文件名等进阶能力。理解这些源码细节有助于在 Windows 桌面应用开发中正确评估数据一致性、选择合适 API并快速定位存储相关的疑难问题。【免费下载链接】packagesA collection of useful packages maintained by the Flutter team项目地址: https://gitcode.com/GitHub_Trending/pac/packages创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考