在鸿蒙应用里处理用户设置、登录状态、开关项这类数据最顺手的方案就是 Preferences。它和安卓的 SharedPreferences、iOS 的 UserDefaults 属于同一类设计——轻量级键值对存储不需要建表、不需要写 SQL拿过来就能用适合保存配置类、偏好类的小数据这也是我日常开发中用到频率最高的本地存储方式之一。把这个组件单独拿出来写一篇是因为不少刚接触鸿蒙的同学容易把它当成“万能存储”什么数据都往里塞或者不清楚它的落盘机制、性能边界、API 版本差异结果写出一堆“存了读不到”“频繁写入卡顿”的疑难杂症。这里我结合自己的项目经验把这套存储方案的定位、用法、调优和坑点一次说清楚。1. 为什么要用 Preferences而不是直接写文件或上数据库1.1 轻量级数据存储的定位在鸿蒙生态里本地持久化方案大致分三类轻量级键值存储 Preferences、关系型数据库 RDB、分布式数据管理服务。三者各有侧重Preferences 负责的是最轻的那一档——应用偏好、用户配置、登录标记、引导页展示状态、历史搜索词这类小数据。这类数据有一个共同特点单条体积小、总量有限、结构简单。比如“深色模式是否开启”本质就是一个布尔值“上次浏览到第几章”可能就是一个数字用户设置的昵称、每日目标也就是一两个字符串。这类信息用数据库存当然也行但杀鸡用牛刀你得建表、写 DAO、管理数据库连接工程上无端多出一堆复杂度。Preferences 则直接把数据以 Key-Value 形式落到沙箱内的本地文件里读写都是现成 API非常省事。说它“轻量”还有一个层面是指对开发者心智负担的轻量。你不需要关心数据库版本升级、表结构变更这些问题只要维护好 key 的命名约定数据读写就像操作一个全局字典。1.2 Preferences 好用在哪相比其他方案Preferences 最大的优势是 API 简单直接。获取实例之后get、put、flush 三个动作就能完成绝大多数场景。读数据有默认值兜底写数据是纯键值覆盖不需要担心并发事务、SQL 注入这类问题。另外Preferences 是线程安全的内部做了并发控制多个页面、多个线程同时读写同一个 Preferences 实例不会出现数据错乱。这个设计很实在实测下来在首页、设置页、弹窗等多个入口同时读写同一个配置项数据一致性是有保障的。还有一个实用功能是数据变更监听。你可以给某个 key 注册监听器在应用内其他模块修改了这个 key 时收到回调页面可以据此做联动刷新。比如用户在设置页把语言切成了英文主界面注册了对应 key 的监听就能及时更新文案不用手动发全局事件。2. Preferences 核心 API 与基础用法2.1 获取 Preferences 实例使用 Preferences 的第一步是获取实例。从 API 9 开始推荐从kit.ArkData导入通过preferences.getPreferences获取指定名称的偏好实例。import { preferences } from kit.ArkData; let options: preferences.Options { name: appSettings }; let dataPreferences: preferences.Preferences await preferences.getPreferences(getContext(this), options);这里的name就是持久化文件的标识最终会在应用沙箱目录下生成对应文件。实际开发中一个应用可以根据业务模块拆多个 Preferences 文件比如登录态单独一个文件、用户偏好单独一个文件。这样做的目的很直接——避免所有 key 挤在一个文件里既便于管理也降低单个文件写入竞争。注意事项getPreferences是异步方法在页面初始化时建议放到合适生命周期里处理不要在aboutToAppear里直接await阻塞 UI 构建。系统也提供了同步版本getPreferencesSync但同步读取会阻塞调用线程不建议在 UI 主线程用。不要对同一个 name 反复调用getPreferences拿新实例全局维护一个单例即可多实例会增加不必要的资源开销。2.2 读取数据get 与默认值兜底Preferences 的读操作很简单get方法传入 key 和默认值返回指定类型的数据。let userName: string await dataPreferences.get(userName, 未登录用户); let darkMode: boolean await dataPreferences.get(darkMode, false); let targetWeight: number await dataPreferences.get(targetWeight, 60);我重点说下类型问题。Preferences 的get返回类型是ValueType即number | string | boolean | Array... | object | Uint8Array等。因为 TS 的类型推断拿不到存储时的具体类型所以很多时候需要自己断言let themeColor: string (await dataPreferences.get(themeColor, #FFFFFF)) as string;一个很容易踩的坑如果存进去的时候是 number 类型取出来却按 string 用运行时就会出现奇怪的问题。所以建议每个 key 的数据类型要固定不要同一个 key 一会儿存字符串一会儿存数字。团队内部可以把所有 key 定义成常量并在注释里标注类型避免后续维护的人踩坑。2.3 写入数据put 与 flush 两段式提交写入 Preferences 是典型的两段式操作先用put更新内存中的缓存再用flush把数据落盘。await dataPreferences.put(darkMode, true); await dataPreferences.flush();put只是修改了实例在内存里的值此时如果应用被系统杀掉数据是不会写到磁盘的。只有调用了flush数据才会真正持久化。这个设计经常被新手吐槽“为什么我存了数据重启应用后丢了”十有八九就是忘记 flush。关于 flush 还有两个细节值得注意flush返回一个 Promise可以在落盘完成后拿到结果。如果对持久化时机有严格要求比如用户在修改关键配置后马上退出应用最好等 flush 完成再做退出逻辑。flushSync是同步落盘版本接口存在但慎用尤其是高频业务里不要用它会阻塞当前线程直到磁盘写入完成对 UI 流畅度影响很明显。如果连续多次修改了多个 key可以统一调用一次 flush而不是每次 put 都 flush 一次这样能显著减少磁盘写入次数。2.4 删除数据与清理文件删除单个 key 用delete删除后同样需要 flush 才能落盘。await dataPreferences.delete(tempFlag); await dataPreferences.flush();需要清空整个 Preferences 文件时可以遍历所有 key 再逐个删除也可以考虑直接删除文件。Preferences 提供了removePreferencesFromCache来释放实例配合文件删除可以完成重置操作。实际项目中做“退出登录清理本地数据”这个功能时我会按业务模块选择清理策略只清理登录相关的 key逐个 delete。退出登录后整机重置用户数据删除对应 Preferences 文件后重新创建实例。这里要特别提醒不要在主线程硬编码大量 key 的循环 delete 再 flush数据量大的时候会有明显的卡顿感建议拆分到子线程或分批次执行。2.5 数据变更监听与其他辅助能力Preferences 支持通过on(change)监听数据变化也可以在flush完成后监听持久化结果。dataPreferences.on(change, (key: string) { // key 是发生变化的键名 if (key darkMode) { // 刷新界面主题 } });这个能力特别适合“多页面联动”的场景。比如设置页改完主题色首页不需要手动传参注册监听后自然能感知变化。需要注意监听器在页面销毁时记得注销否则会造成内存泄漏。此外Preferences 还提供数据导出export和导入import能力可以把偏好数据导出成文件再导入到另一台设备的同应用里。这在某些需要数据迁移的场景下很有用不过平时用得少需要时查一下 API 文档即可。3. 完整场景实战用户偏好设置从设计到代码落地3.1 需求与方案设计这里用一个具体的例子走完整套流程做一个健康管理应用的“我的设置”页面需要持久化以下数据用户昵称是否开启每日提醒目标步数偏好语言是否首次启动这些数据全部属于轻量级配置用 Preferences 正合适。我会为设置类数据单独开一个 name 为 “userSettings” 的 Preferences 文件key 的规划如下key类型默认值说明nicknamestring空字符串用户昵称dailyReminderbooleantrue每日提醒开关targetStepsnumber8000目标步数languagestringzh-CN界面语言isFirstLaunchbooleantrue是否首次启动把 key 整理成常量类方便复用也降低硬编码造成的拼写错误风险。export class SettingsKeys { static readonly NICKNAME nickname; static readonly DAILY_REMINDER dailyReminder; static readonly TARGET_STEPS targetSteps; static readonly LANGUAGE language; static readonly IS_FIRST_LAUNCH isFirstLaunch; }3.2 页面上的业务代码在设置页读取数据并渲染import { preferences } from kit.ArkData; import { SettingsKeys } from ./SettingsKeys; async function loadSettings(context: Context): PromiseSettingsModel { const pref await preferences.getPreferences(context, { name: userSettings }); const nickname await pref.get(SettingsKeys.NICKNAME, ) as string; const dailyReminder await pref.get(SettingsKeys.DAILY_REMINDER, true) as boolean; const targetSteps await pref.get(SettingsKeys.TARGET_STEPS, 8000) as number; const language await pref.get(SettingsKeys.LANGUAGE, zh-CN) as string; const isFirstLaunch await pref.get(SettingsKeys.IS_FIRST_LAUNCH, true) as boolean; return { nickname, dailyReminder, targetSteps, language, isFirstLaunch }; }修改数据的入口比如用户切换了提醒开关async function updateReminder(context: Context, enabled: boolean) { const pref await preferences.getPreferences(context, { name: userSettings }); await pref.put(SettingsKeys.DAILY_REMINDER, enabled); await pref.flush(); }注意这里每次都重新获取了 Preferences 实例。实际项目里这不是最佳做法更推荐把getPreferences的结果保存成一个全局单例首次启动时初始化一次后续所有页面复用同一个实例。我一般在应用入口的初始化逻辑里统一获取并注入到全局状态管理里而不是散落在各个页面里重复获取。3.3 首次启动与状态恢复首次启动标记是 Preferences 最典型的使用场景之一。应用第一次启动时显示引导页后续启动直达首页这个标记就存在 Preferences 里。async function checkFirstLaunch(context: Context): Promiseboolean { const pref await preferences.getPreferences(context, { name: appMeta }); const isFirst await pref.get(SettingsKeys.IS_FIRST_LAUNCH, true) as boolean; if (isFirst) { await pref.put(SettingsKeys.IS_FIRST_LAUNCH, false); await pref.flush(); } return isFirst; }这个场景的关键点在于标记位必须在引导页成功展示之后再置为 false而不是应用一启动就改掉。否则用户可能还没看完引导页下次启动就直接进首页了。实际中我也会在引导页的“开始使用”按钮点击回调里再去修改这个标记逻辑更准确。3.4 设置项变更的联动处理用户在设置页改了语言主页面需要同步刷新。用 Preferences 的 change 监听就能优雅地实现跨页面联动。pref.on(change, (key: string) { if (key SettingsKeys.LANGUAGE) { // 触发语言切换 } });需要注意on(change)监听在实例释放后也会一并失效。开发中我习惯在页面aboutToDisappear或组件的生命周期结束里注销监听避免页面已经销毁了回调还执行带来不必要的报错或内存占用。4. 高能避坑指南flush 阻塞、数据加密与 API 版本差异4.1 flush 的副作用和写入频率控制Preferences 官方设计是偏向“低频小数据”的但实际业务里总有人拿它做高频写入比如每秒记录一次位置信息或频繁更新进度值。这时候系统会明显感受到压力因为每次 flush 都是一次完整的磁盘 I/O在高频调用下会拖慢 UI 线程甚至引发卡顿。解决思路有几个降低 flush 频率多次 put 后统一 flush。合并写入对实时性要求不高的数据做一个简单的节流控制比如 5 秒攒一次批一次性 flush。评估存储方案高频、结构化、量大的业务数据应该使用关系型数据库或分布式数据服务而不是 Preferences。另外要注意flush和flushSync之间的取舍。flushSync在文档里说是“同步将数据写入磁盘”听起来挺好但实际会阻塞调用线程。UI 线程上调用 flushSync 时磁盘写入的耗时直接反映到界面卡顿上非常明显。我自己的原则是 UI 线程只用异步 flushflushSync 只在子线程的任务里才考虑。4.2 数据安全与加密存储Preferences 默认是明文存储在沙箱目录里的虽然应用沙箱本身就限制了其他应用的访问但如果设备存在恶意软件或用户对文件系统做了特殊操作数据仍然有被读取的风险。对于 token、用户敏感信息这类数据默认存储方式显然不够安全。从 API 14 开始Preferences 支持对实例的持久化文件进行加密。通过setEncryptOptions接口可以把一个普通 Preferences 实例升级为加密存储。这块我踩过一次坑加密的粒度是文件级一旦对某个 Preferences 文件启用加密整个文件的读写都走加解密流程性能会有一定下降。所以加密只应该用于确有必要的数据文件不要无脑对所有 Preferences 加密。像是“界面语言”“目标步数”这类非敏感数据加不加密意义不大反而白白增加读写开销。另外一个容易被忽略的点加密数据和未加密数据的文件在整体系统备份、云同步场景下表现可能不同。如果你的应用做了云备份功能需要确认备份服务对加密 Preferences 文件的支持情况避免出现备份文件无法恢复的问题。4.3 不同 API 版本的接口演进Preferences 的接口在鸿蒙版本演进中有明显调整。早期 API 8 阶段模块路径是ohos.data.preferencesAPI 9 之后统一归入kit.ArkData这个变化对存量工程影响很大。在我维护的老项目里就有直接 import 旧路径导致编译失败的案例。解决方式是把整个数据存储模块的导入路径统一改到kit.ArkData。同时部分接口签名也有调整最典型的是部分方法从同步返回改成了 Promise 或 callback 形式。如果项目的 compileSdkVersion 升级了旧的调用方式可能编译报错或拿到 undefined。建议新项目直接从kit.ArkData开始写不要再接触旧模块路径。升级 API 版本后全局搜索旧路径和相关方法的调用逐个确认兼容性。留意废弃接口警告有些接口在旧版本还能跑但后续版本会真的移除。4.4 存储规格限制不是所有数据都能塞Preferences 的量级限制常常被忽略这里把关键规格列出来项目上限持久化文件大小约 64KB单个 key 长度≤ 80 字符单个 value 大小≤ 8192 字节这个限制意味着Preferences 不适合保存大文本、长日志、图片转码字符串等数据。比如把一张图片的 Base64 字符串放进去直接超限写入失败或数据截断。我之前有个同事把一段很长的用户协议内容存 Preferences结果读出来的内容不完整排查了很久才发现是大小超限被截断了。超过这些量级的数据正确的归属是关系型数据库或者直接存文件系统、应用级文件目录。Preferences 做好自己的轻量定位就好。5. 高频踩坑问题排查与工程化建议5.1 常见问题速查表问题现象根本原因解决方案数据写入后重启丢失只调用 put 没有 flush每次修改后调用 flush或批量修改后统一 flush读取到的数据是默认值key 拼写不一致统一用常量类管理 key不用裸字符串数据读取类型不对存的类型和取的类型不一致key 与数据类型强绑定注释标明高频 flush 导致 UI 卡顿磁盘写入过于频繁合并写入、节流 flush或更换存储方案大文件写入失败超过 Preferences 大小限制换 RDB 或文件系统存储监听回调不触发实例已被释放或没有注册成功检查注册时机和实例生命周期升级 API 版本后方法找不到接口被迁移或签名变化改用kit.ArkData新接口5.2 工程化落地经验最后分享几个我在实际项目中总结出来的习惯这些细节不写进官方文档但对项目的可维护性和稳定性影响很大。第一个是 key 命名规范。我见过不少人写 Preferences 直接写字符串键名时间一长代码里遍布裸字符串根本没法维护。我会把所有 key 集中到一个常量类或模块按业务域分组命名。同时习惯用“模块_用途”的命名规则比如setting_darkMode、user_token这样日志和问题排查时能快速定位数据归属。第二个是分区存储。不要把所有 key 放一个 Preferences 文件里。登录态、用户设置、业务缓存分别用不同的 name 建独立文件。这样在“退出登录只清登录态”这个操作里可以直接删除对应文件不会误删用户设置。分区合理的话flush 之间的互相影响也小。第三个是实例复用。一个 Preferences 文件对应一个全局实例应用启动时初始化一次后续需要时通过依赖注入或全局访问器获取。不要每个页面都调getPreferences拿新实例。反复创建实例一方面浪费资源另一方面如果操作不同实例引用同一文件会引入不可预期的同步问题。第四个是数据迁移意识。如果应用之前用的是其他存储方案比如直接写 JSON 文件或使用 SharedPreferences迁移到鸿蒙 Preferences 时需要写一个一次性的迁移逻辑把老数据读出来再写入 Preferences。这个逻辑建议放在应用启动的初始化阶段迁移完成后设置一个标记位避免每次启动都重复迁移。6. 写在最后一些个人体会Preferences 这组件说大不大说小不小但每个鸿蒙应用基本都绕不开它。我自己用过不少本地存储方案最后还是觉得 Preferences 在“配置类数据”这个场景里最舒服——API 简单、并发安全、监听机制好用只要不把它用错地方它几乎不会给你添麻烦。如果要从这篇文章里提炼三个最关键的记忆点我个人的排序是第一flush 才是真正的落盘动作put 只是改内存第二key 一定要统一管理别用裸字符串第三超限数据及时换存储方案别在 Preferences 上死磕。记住这三条Preferences 用起来基本就稳了。现在每次新开鸿蒙项目我做的第一件事就是把数据存储模块的初始化搭好把 key 常量、分区策略、实例管理一次配齐后面业务开发时完全不用再操心本地数据这块。希望这篇内容也能让读者少踩几个坑省下折腾的时间去做真正有价值的业务功能。