JSOS
使用指南

持久化目录

让指定目录的内容在刷新后保留

持久化目录

WebContainer 的文件系统在页面刷新后会重置。应用代码目录和 DATA_DIR 有各自的快照机制,而其他目录(如 ~/.pi、~/.config)默认不会保留——需要把它们加入持久化列表。

添加目录

设置 → 持久化

  1. 打开设置应用
  2. 选择「持久化」
  3. 点击「添加」,用目录浏览器选择 workdir 下的目录
  4. 保存后立即开始监听

CLI

jsos persist add .pi
jsos persist list

# 相对路径按当前 shell 目录解析
cd ~/test
jsos persist add ./data   # 持久化 test/data
jsos persist add ~/test   # 持久化 test(~ 展开为 workdir)

规则

规则说明
相对路径CLI 按当前 shell 目录解析(cd ~/test && jsos persist add ./data → test/data);API/GUI 按 workdir 解析;~ 展开为 workdir
不能含 ..防止路径越界
重复添加同一路径再次添加为幂等操作(返回 alreadyExists),不会报错
不嵌套不能与已有条目互为父子路径(父目录、子目录都会拒绝)
保留前缀workspace、.tmp 不能作为持久化目录
必须在 workdir 内workdir($HOME)之外的路径无法被 WebContainer 导出 / 挂载

快照机制

  • 目录变更后约 1 秒防抖导出为二进制快照
  • 快照存入 IndexedDB(jsos-userdata)
  • 刷新页面时自动挂载恢复
  • 设置页显示最近快照时间与大小

重命名与移除

  • 重命名:数据随快照迁移到新路径
  • 移除:停止监听,容器内文件保留;默认保留快照(再次添加同路径可恢复),选择「同时删除快照」才会清除;CLI 移除前会确认一次(-y 跳过)
jsos persist rename .pi .pi-new
jsos persist remove .pi          # 确认后保留快照
jsos persist remove .pi --purge -y  # 跳过确认,同时删除快照

API

window.JSOS.getUserDataDirs() / addUserDataDir() / renameUserDataDir() / removeUserDataDir() / browseWorkdir(),详见 JSOS API - 持久化目录管理。

On this page