系列：HarmonyOS 开发入门 · 10

“把数据存本地”听起来是一件事，实际有完全不同的几类需求。

主题色、登录开关、用户草稿、10000 条历史记录，如果都用同一种方式存，迟早会难受。

这篇不追求把所有 API 都讲完，先建立选型思路。

1. Preferences：轻量键值配置

适合：

• 是否首次启动；
• 用户选择的主题；
• 简单开关；
• 少量字符串、数字、布尔值。

导入：

import { preferences } from '@kit.ArkData'
import { common } from '@kit.AbilityKit'

保存：

async function saveTheme(context: common.Context): Promise<void> {
  const store = await preferences.getPreferences(context, 'settings')
  await store.put('theme', 'dark')
  await store.flush()
}

读取：

async function readTheme(context: common.Context): Promise<string> {
  const store = await preferences.getPreferences(context, 'settings')
  const value = await store.get('theme', 'system')
  return value as string
}

Preferences 最大的优点就是简单。

但不要用它存大列表、复杂关系数据。

2. PersistentStorage：更偏 UI 状态持久化

ArkUI 里有 AppStorage / PersistentStorage 这套状态管理思路。

它适合把某些全局状态和持久化联系起来，例如 UI 偏好。

但它不是“万能数据库”。

业务数据需要查询、排序、分页、条件过滤时，应该考虑真正的数据存储方案。

3. 文件：适合大块原始内容

例如：

• JSON 缓存；
• 下载文件；
• 图片；
• 导出文档；
• 临时数据。

使用文件系统时，关键不是“会不会 write”，而是区分：

cacheDir
filesDir
数据库目录
用户选择的外部文件 URI

不同目录生命周期和访问语义不同。

缓存文件可以被清理，重要文件就不要只放缓存目录。

4. RelationalStore：结构化数据

当数据出现下面这些需求时，我会优先考虑关系型数据库：

• 多字段；
• 多条记录；
• 条件查询；
• 排序；
• 分页；
• 更新和删除；
• 数据关系逐渐复杂。

HarmonyOS 的关系型数据库基于关系模型提供 CRUD 和 SQL 能力。

典型配置：

import { relationalStore } from '@kit.ArkData'

const config: relationalStore.StoreConfig = {
  name: 'app.db',
  securityLevel: relationalStore.SecurityLevel.S1
}

5. 一个非常实用的选型表

数据	推荐
是否首次启动	Preferences
主题、语言等偏好	Preferences / PersistentStorage
用户头像缓存	文件
导出的 PDF	文件
记账流水 5 万条	RelationalStore
聊天记录	RelationalStore
临时接口缓存	文件或专门缓存层

6. 不要把 Token 当普通配置随便存

认证 Token、密码、密钥这类数据和普通 UI 配置不是一个安全级别。

敏感凭据应该使用专门的安全存储能力，而不是为了方便直接扔进 Preferences 明文保存。

这是工程上很值得提前建立的意识。

7. 我最常见到的错误

错误一：所有东西都 Preferences

刚开始简单，后面要查询时彻底崩。

错误二：两条数据也先建十张表

过度设计一样浪费时间。

错误三：缓存和持久化不区分

把重要数据只放 cacheDir，被清理以后才发现。

8. 一个简单原则

我一般问自己：

这份数据是“配置”、是“文件”，还是“记录集合”？

• 配置 -> Preferences；
• 文件 -> 文件系统；
• 记录集合 -> 数据库。

大部分选型已经解决了。

总结

存储没有“最强方案”，只有合适方案。

初学阶段先把 Preferences 用熟，再理解文件 URI 和关系型数据库，比一开始引入一堆三方 ORM 更稳。

下一篇进入权限。权限问题是 HarmonyOS 真机开发中出现频率非常高的一类问题，尤其是“声明了为什么不弹”“拒绝后为什么再也不弹”。