使用指南
持久化目录
让指定目录的内容在刷新后保留
持久化目录
WebContainer 的文件系统在页面刷新后会重置。应用代码目录和 DATA_DIR 有各自的快照机制,而其他目录(如 ~/.pi、~/.config)默认不会保留——需要把它们加入持久化列表。
添加目录
设置 → 持久化
- 打开设置应用
- 选择「持久化」
- 点击「添加」,用目录浏览器选择 workdir 下的目录
- 保存后立即开始监听
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 - 持久化目录管理。