cloudPath必须带分类前缀和扩展名，推荐格式为"${category}/${timestamp}-${random}.${ext}"，如"avatar/1749992345-abc123.jpg"；分类目录名限英文、数字、短横线，扩展名须小写且来自原文件；前端须立即生成带分类的cloudPath，云函数仅做上传后校验与元数据处理。
uniCloud.uploadFile 的 cloudPath 必须带分类前缀和后缀
上传时的 cloudPath 不是随便拼的路径，它直接决定文件在云存储里的存放位置和可访问性。不加分类前缀（如 "avatar/"、"post/image/"）会导致所有文件混在一起，后续查、删、权限控制都变麻烦。
常见错误是写成 "123.jpg" 或 "user/123" —— 前者没分类，后者缺扩展名，腾讯云会静默失败，返回空 fileID；阿里云可能报 invalid file path 但不提示原因。
-
cloudPath推荐格式："${category}/${timestamp}-${random}.${ext}"，例如"avatar/1749992345-abc123.jpg" - 分类目录名必须是英文、数字、短横线（
-），禁止中文、空格、下划线 - 扩展名必须来自原始文件（用
path.extname(originalName)提取），且转为小写（.JPG→.jpg） - 阿里云默认不启用真实路径结构，若需按
cloudPath生成子目录，上传时要显式传{ cloudPathAsRealPath: true }
前端选图后立即生成带分类的 tempFilePath + cloudPath
分类逻辑不能丢给云函数做——因为 tempFilePath 只存在于客户端本地，30 秒内有效，传到云函数里只剩一个字符串，无法读取文件内容或元信息。
所以分类判断必须在前端完成：根据业务场景决定走哪个分类，比如头像上传用 "avatar/"，文章配图用 "post/image/"，身份证照片用 "idcard/"（后续可配私有权限）。
- 调用
uni.chooseImage或uni.chooseMedia后，立刻从res.tempFiles[0].path和res.tempFiles[0].name提取扩展名 - 不要用
res.tempFilePaths[0]（H5 不支持，且部分平台已弃用） - 分类字段建议通过页面参数、data 属性或 vuex store 传递，避免硬编码在云上传调用里
- 示例片段：
const ext = '.' + (file.name.split('.').pop() || 'png').toLowerCase(); const cloudPath = `avatar/${Date.now()}-${Math.random().toString(36).substr(2, 6)}.${ext}`; uniCloud.uploadFile({ filePath: file.path, cloudPath });
云函数里只做分类后的校验与元数据写入，不碰文件上传
有人想让云函数统一接管上传，再按类型分发——这不可行。云函数无法访问客户端的 tempFilePath，也无法触发二次上传。
真正该由云函数处理的是上传成功后的动作：比如检查 fileID 对应的图片尺寸是否超标、是否命中敏感词、是否需要生成缩略图，然后把分类信息、尺寸、大小等写入数据库。
- 上传成功回调里调用
uniCloud.callFunction，传{ action: 'saveRecord', fileID, category: 'avatar', ... } - 云函数收到后，用
uniCloud.downloadFile拉取图片做校验（仅限必要场景，避免浪费流量） - 数据库记录中必须存
category字段，方便后续按分类查列表、批量删、设置 CDN 缓存策略 - 隐私类分类（如
"idcard/"）应在云存储控制台设为「仅云函数可读写」，前端展示时用uniCloud.getTempFileURL拿临时链接
分类路径影响 CDN 缓存与权限配置
云存储不是普通文件夹，分类路径实际是 CDN 路径的一部分。不同分类可以配置不同缓存策略或权限模型，但前提是路径结构清晰、命名规范。
比如 "public/avatar/" 可设为公开读，"private/idcard/" 设为私有，而 "temp/upload/" 可配 1 小时自动过期策略。这些都依赖 cloudPath 的层级设计。
- 避免嵌套过深：超过 3 级（如
"user/profile/avatar/"）会增加 CDN 解析开销，也难管理 - 不要动态拼接用户 ID 到路径里（如
"user/123/avatar.jpg"），除非你确认该用户 ID 永远不变；更稳妥的是用fileID关联关系，路径保持静态分类 - 支付宝云支持「私有权限文件夹」，可直接把
"idcard/"目录设为私有，所有上传到该路径的文件自动继承权限 - 腾讯云/阿里云需在控制台手动为每个分类路径配置权限，漏配就等于裸奔
分类不是起个文件夹名字那么简单——它绑定了权限、缓存、CDN 路由、数据库查询逻辑，甚至影响灰度发布时的流量隔离。最易被忽略的是：路径里用了中文或空格，导致 CDN 返回 404，但控制台里文件明明存在。
