鸿蒙开发手册HARMONYOS

CHAPTER 06本地存储 · PERSISTENCE

数据持久化

App 关掉再打开数据还在。从最简单的 Preferences 到关系型 RDB,再到文件与安全存储,每种方案都有自己的主场。

开始阅读难度进阶约3小时
06.1

持久化全景

按数据量、结构复杂度与安全性选型:偏好用 Preferences,结构化关系用 RDB,大文件用文件系统,密钥用加密存储。

分布式能力

鸿蒙提供分布式数据管理,可在同一账号的多设备间同步(需权限与设备协同),适合跨端场景。

06.2

Preferences

Preferences 存轻量键值,异步读写,适合设置项与小状态。

import preferences from '@ohos.data.preferences'
const pref = await preferences.getPreferences(context, 'settings')
await pref.put('dark', true)
await pref.flush()
const dark = await pref.get('dark', false)
06.3

RDB 关系型

RDB(关系型数据库)适合结构化、需查询的数据,用 SQL 建表与查询,返回结果集。

import rdb from '@ohos.data.relationalStore'
const store = await rdb.getRdbStore(context, { name: 'app.db', securityLevel: rdb.SecurityLevel.S1 })
await store.executeSql('CREATE TABLE IF NOT EXISTS user (id INTEGER PRIMARY KEY, name TEXT)')
const rs = await store.querySql('SELECT * FROM user WHERE id = ?', [1])
06.4

文件与媒体

用 @ohos.file.fs 读写应用沙箱文件;媒体用媒体库 API,遵循安全访问规范。

import fs from '@ohos.file.fs'
const file = fs.openSync(path, fs.OpenMode.READ_WRITE | fs.OpenMode.CREATE)
fs.writeSync(file.fd, buffer)
fs.closeSync(file)
06.5

安全存储

令牌、密钥用加密文件系统(如 Asset/加密 Preferences)存储,明文绝不放普通文件。

密钥管理

敏感凭证优先用系统密钥库(Asset),避免硬编码或明文落地。

06.6

KVStore 分布式

通过分布式键值/数据库,可在同一账号设备间同步数据,适合跨端偏好与状态。

06.7

选型对照

方案适合
Preferences偏好/小键值
RDB结构化关系数据
文件文档/媒体/缓存
Asset/加密密钥、令牌
06.8

常见陷阱

为什么写入没生效?

Preferences 需调用 flush() 才落盘;RDB 需确认事务提交。异步 API 要 await 完成。

数据库升级怎么迁移?

通过 version 字段在 onUpgrade 中执行 ALTER/建表迁移;忽略会导致老用户升级崩溃。

06.9

实战练习

延伸资源