JSOS
开发指南

数据持久化

应用数据的读写、存储和同步

数据持久化

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 的文件会自动:

  1. 被 fs.watch 检测到变更
  2. 1 秒防抖后导出为二进制快照
  3. 存入 IndexedDB shared-data-snapshots store
  4. 页面刷新时自动恢复

整个过程是自动的,你只管读写文件即可。

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%)
  • 不同应用之间的数据隔离,互不干扰

On this page