开发指南
数据持久化
应用数据的读写、存储和同步
数据持久化
DATA_DIR
每个应用启动时自动创建专属数据目录,通过环境变量 DATA_DIR 访问:
const dataDir = process.env.DATA_DIR;
// 例如:/home/{user}/workspace/data/my-app你可以在这个目录下读写任何文件,这些文件会被自动同步到浏览器的 IndexedDB 中。下次刷新页面或重新打开应用时,数据自动恢复。
import { writeFile, readFile, mkdir } from 'fs/promises';
import { join } from 'path';
// 写数据
const dataPath = join(process.env.DATA_DIR, 'data.json');
await writeFile(dataPath, JSON.stringify({ hello: 'world' }));
// 读数据
const data = JSON.parse(await readFile(dataPath, 'utf-8'));数据同步机制
写入 DATA_DIR 的文件会自动:
- 被
fs.watch检测到变更 - 1 秒防抖后导出为二进制快照
- 存入 IndexedDB
shared-data-snapshotsstore - 页面刷新时自动恢复
整个过程是自动的,你只管读写文件即可。
APP_DIR
APP_DIR 指向应用代码目录。一般不需要往这里写数据,但可以读取:
const packageJson = await readFile(join(process.env.APP_DIR, 'package.json'), 'utf-8');用户数据目录(持久化目录)
除了 DATA_DIR,还可以把 workdir 下的任意目录加入持久化列表(如 ~/.pi、~/.config),其内容同样会被监听并快照到 IndexedDB,刷新后恢复。
管理方式:
- 设置 → 持久化 页面(添加 / 重命名 / 移除,内置目录浏览器)
- CLI:
jsos persist list/add/rename/remove - JSOS API:
getUserDataDirs/addUserDataDir/renameUserDataDir/removeUserDataDir/browseWorkdir
# 让 ~/.pi 在刷新后保留
jsos persist add .pi
# 查看持久化目录与快照状态
jsos persist list规则:
- 路径必须相对 workdir(如
.pi),不能是绝对路径,也不能包含.. - 不能与已有条目重复或互为父子路径
workspace、.tmp为保留前缀- 目录必须位于 workdir(
$HOME)内部;workdir 之外的路径无法持久化
详见 持久化目录管理。
卸载时保留/删除数据
卸载应用时可以选择:
- 保留数据 — 数据仍在 IndexedDB 中,重装后可用
- 删除数据 — 清理数据目录
注意事项
- 数据存储在浏览器本地(IndexedDB),清除浏览器数据会丢失
- 数据容量受 IndexedDB 限制(通常为浏览器可用空间的 50%)
- 不同应用之间的数据隔离,互不干扰