用途:在 Convex 中完成文件的上传、存储、提供与删除,适用于用户上传图片或文档、action 从第三方抓取文件、以及文件 URL 意外过期等场景。
主要能力:提供 generateUploadUrl、saveFile、listMine、remove 等函数;支持在 action 与 HTTP action 中用 ctx.storage.store 存储 blob;支持用 ctx.storage.getUrl 在查询中解析 URL,或通过 HTTP action 在 https://<deployment>.convex.site/files/<storageId> 提供文件;可从 _storage 系统表读取 contentType、sha256、size 等元数据。
使用方式:上传分三步——mutation 发放短期上传 URL,客户端 POST 文件,第二个 mutation 保存返回的 storageId。上传 URL 一小时后过期,每次上传需重新生成且不可存储。schema 中用自己的表保存名称、所有者等应用元数据,并以 v.id("_storage") 指向 _storage。服务端校验用 ctx.db.system.get 读取真实大小与类型,客户端校验仅用于体验。删除时在同一 mutation 中同时删除 blob 与行,并校验所有权。
限制与注意:ctx.storage.store 仅在 action 和 HTTP action 中可用,mutation 中不可用;ctx.storage.getMetadata 已废弃,应改用 ctx.db.system.get;HTTP action 有 20MB 请求上限,大文件应走上传 URL 流程;上传 POST 需带 Content-Type,否则文件以 application/octet-stream 提供;getUrl 在文件被删除时返回 null,UI 需处理。
文档:https://docs.convex.dev/llms.txt、https://docs.convex.dev/file-storage/upload-files、https://docs.convex.dev/file-storage/serve-files、https://docs.convex.dev/file-storage/file-metadata