Convex File Storage 是面向 Convex 后端的文件处理技能，涵盖上传、存储、服务与元数据管理，并给出可直接参考的实现代码。
用途 用于在 Convex 应用中实现文件上传、生成上传 URL、提供文件访问、管理文件元数据等场景，覆盖上传流程、文件服务、删除、Schema 定义、图片处理与 HTTP 文件服务等主题。
主要能力
- 上传流程：通过 mutation 调用 ctx.storage.generateUploadUrl() 生成上传 URL；客户端以 POST 方式将文件直接上传至 Convex 存储，并从响应中取得 storageId；再用 mutation 将 storageId、fileName、fileType、uploadedBy、uploadedAt 等写入 files 表。
- 文件服务：通过 query 使用 ctx.storage.getUrl(storageId) 获取文件 URL；getFile 查询可同时返回文件 URL 与 fileName、fileType 等元数据。
- 删除文件：deleteFile mutation 先从存储删除 blob（ctx.storage.delete），再删除数据库中的元数据记录，并对未找到文件抛出 ConvexError。
- Schema 定义：files 表包含 storageId、fileName、fileType、可选 fileSize、uploadedBy、uploadedAt，并建立 by_uploader 与 by_type 索引。
- 图片处理：saveImage mutation 记录 storageId、width、height、createdAt；客户端示例展示预览、读取 naturalWidth/naturalHeight、上传并保存尺寸的完整 React 组件流程。
- HTTP 文件服务：在 convex/http.ts 中通过 httpRouter 定义 GET /files/{storageId} 路由，用 ctx.storage.get(storageId) 取出 blob 并返回 Response，缺少 storageId 返回 400，文件不存在返回 404。
使用方式 在 Convex 项目的 convex 目录下创建 files.ts、schema.ts、http.ts 等文件，按示例定义 mutation、query 与 HTTP Action，并在客户端调用生成的 api 方法完成上传与读取。上传时需带上文件的 Content-Type 请求头。官方参考链接：https://docs.convex.dev/file-storage 与 https://docs.convex.dev/functions/http-actions。
适用场景 适合需要用户上传文件、保存文件引用、按元数据查询文件、按 storageId 提供下载、管理图片尺寸的 Convex 应用。
限制与注意事项 默认最大文件大小为 20MB；更大文件需使用分块上传或外部存储。删除文件时必须同时删除元数据与存储 blob；应在客户端与服务端校验文件类型；提供文件前应加所有权检查，避免暴露全部文件；上传失败需妥善处理错误。