jokymouse.fs API

jokymouse.fs 模块通过 require("jokymouse.fs") 加载，提供按脚本隔离的文件读写能力。

local fs = require("jokymouse.fs")

文件空间

jokymouse.fs 使用 URI 风格的路径。默认情况下，脚本只能访问属于自己的私有空间，不会读写其他脚本的数据。

协议	普通模式	开发模式	说明
`data://`	可用	可用	脚本私有持久数据
`cache://`	可用	可用	脚本私有缓存，可由用户清理
`temp://`	可用	可用	脚本私有临时文件
`file://`	不可用	可用	真实本地文件系统路径

示例：

local fs = require("jokymouse.fs")

fs.write_text("data://state.json", '{"step":1}')
local state = fs.read_text("data://state.json")
print(state)
print(fs.resolve("data://state.json"))

可用函数

函数	签名	说明
read_text	`fs.read_text(path)`	读取 UTF-8 文本文件
write_text	`fs.write_text(path, content)`	覆盖写入 UTF-8 文本文件
append_text	`fs.append_text(path, content)`	在文件末尾追加 UTF-8 文本
exists	`fs.exists(path)`	判断文件或目录是否存在
resolve	`fs.resolve(path)`	将 URI 路径解析为本机绝对路径，便于调试
read_dir	`fs.read_dir(path)`	读取目录项名称列表
create_dir	`fs.create_dir(path)`	递归创建目录
remove_file	`fs.remove_file(path)`	删除文件，返回是否真的删除
copy_file	`fs.copy_file(from, to)`	复制文件，返回复制字节数
read_json	`fs.read_json(path)`	读取 JSON 文件并解析为 Lua 值
write_json	`fs.write_json(path, value)`	将 Lua 值序列化为 JSON 写入

限制

单文件大小限制 1MB，超过会失败。
每个脚本的私有空间 data://、cache://、temp:// 合计最多保存 100 个文件；目录不计入数量，删除文件后会释放名额。
路径中不能包含 .. 进行目录穿越。
file:// 仅开发模式可用；文件大小没有限制。

开发模式

开发模式下，file:// 会被允许，用于调试本机文件。例如：

local jm = require("jokymouse")
local fs = require("jokymouse.fs")

if jm.is_dev_mode() then
  local text = fs.read_text("file://C:/Users/me/Desktop/input.txt")
  print(text)
end

开发模式脚本不能发布到市场。即使你关闭开发模式，发布时仍会扫描源码；只要脚本里保留 file://、io、os.execute、dofile、loadfile 等开发专属或危险能力，提交也会被拒绝。

与 jokymouse.storage 的区别

jokymouse.storage 适合保存少量结构化状态，单脚本限制 64KB。

jokymouse.fs 适合保存日志、缓存、配置文件或较大的文本数据。普通模式下仍然只允许访问脚本私有空间。