自定义元数据

兼容状态

云沙箱当前不支持文件自定义元数据。普通文件写入、读取以及 getInfo()、list()、rename() 返回的常规文件元信息不受影响。

文件自定义元数据与 Sandbox 控制面元数据是两项不同能力：

• 文件自定义元数据通过 sandbox.files.write(..., metadata=...) 写入，并随文件保存。云沙箱当前不支持该能力。

• Sandbox 控制面元数据在创建 Sandbox 时通过 Sandbox.create(..., metadata=...) 写入，用于标记、查询和关联 Sandbox。该能力不受本限制影响。

失败行为

Python SDK e2b==2.31.0 的 files.write() 方法签名接受 metadata。这不代表当前后端已支持该能力。

Sandbox 当前上报 envd 0.5.2，而 SDK 要求文件自定义元数据使用 envd 0.6.2 或以上版本。调用会在请求发送前失败：

e2b.exceptions.TemplateException:
File metadata requires envd 0.6.2 or later.

因此，这类异常不是 Python 参数不存在，也不影响未传入 metadata 的普通文件读写。升级 SDK 或仅修改 envd 版本号声明无法绕过限制；该能力需要运行环境完整支持元数据校验、键名小写化和扩展属性持久化。

替代方案

在文件自定义元数据开放前，可以选择以下方案：

• 将文件标签保存在业务数据库或对象存储中，并使用 Sandbox ID 和文件路径建立关联。

• 在同一目录写入 JSON 清单文件，记录文件路径和业务标签。需要跨 Sandbox 保留数据时，同时把文件与清单写入 NAS、OSS 等外部存储。

• 如果只需要标记或查询 Sandbox，使用 Sandbox 控制面 metadata，不要将其当作文件元数据。