头像裁剪必须前端裁剪后上传，需统一处理平台差异：小程序/App用uni.getImageInfo获取信息，H5用URL.createObjectURL；裁剪组件需v-if控制、$nextTick+setTimeout确保DOM就绪；输出控制尺寸≤400×400px、格式优先JPEG、质量0.8；base64须转临时文件再上传。
直接用 uni.chooseImage 拿到图后不能传给后端，必须前端裁剪完再上传——这是头像裁剪最核心的约束，绕不开。
选图阶段：uni.chooseImage 的平台差异必须处理
小程序和 App 返回的是临时路径（tempFilePaths[0]），但这个路径不能直接读取像素；H5 返回的 tempFiles[0].path 是本地文件 URL，可直接用于 canvas 加载。不区分平台直接塞进裁剪组件，90% 会白屏或报错。
- 统一做法：不管哪端，都先调
uni.getImageInfo({ src: path })获取宽高、base64（部分平台支持）或用于后续 canvas 绘制 - H5 环境若遇到跨域或 blob 路径加载失败，改用
URL.createObjectURL(file)+input[type="file"]更稳 - 务必加
count: 1，避免多图逻辑污染裁剪流程 - 别只写
sourceType: ['album']，头像场景要同时支持['camera', 'album']
裁剪组件初始化：v-if + $nextTick + setTimeout 缺一不可
常见报错 document is not defined 或 Cannot read property 'getElementById' of null，本质是 DOM 还没挂载，或在 App 端执行了 H5 专属代码。
- 用
v-if="showCropper"包裹裁剪组件，图片加载完成后再设为true - 初始化 cropper 实例前，必须等 DOM 就绪：
this.$nextTick(() => setTimeout(() => { /* new Cropper(...) */ }, 0)) - 运行时守卫加一层：
if (uni.getSystemInfoSync().platform === 'app') return，App 端跳过前端裁剪，走原生或降级方案 - 别在
data或onLoad里直接实例化，放到用户触发裁剪动作后的函数里
裁剪输出：尺寸、格式、质量三者必须协同控制
用户随手拍的图动辄 3–5 MB，裁剪后不压缩直接上传，接口超时、带宽浪费、后端拒收都是大概率事件。
- 目标尺寸建议 ≤ 400×400px，头像常用 200×200 或 300×300，用
canvas绘制时主动缩放，别依赖插件默认输出大小 - 无透明需求（如头像）优先用
canvas.toDataURL('image/jpeg', 0.8)；需透明背景才用image/png，但得确认后端真能解析 PNG - 真机上 canvas 物理像素偏移？按
uni.getSystemInfoSync().pixelRatio调整 canvas 宽高，否则裁剪框和实际区域错位 - uni-app 提供的
uni.compressImage可作为兜底压缩，但不如 canvas 控制精准，建议仅用于降级场景
保存与上传：base64 转 file 或 Blob 更稳妥
很多插件返回的是 base64 字符串，直接传给 uni.uploadFile 的 filePath 字段会失败——它只认本地路径或临时文件路径，不认 base64。
- 正确做法：用
uni.getFileSystemManager().writeFile把 base64 写成临时文件，再把生成的路径传给uni.uploadFile - 或者用
fetch+Blob构造 FormData 手动上传（H5 可行，小程序需uni.uploadFile） - 注意 iOS 小程序对 base64 长度有限制，超长会截断，必须转临时文件
- 上传前检查
res.path是否存在，某些插件在取消或失败时也返回空字符串，容易导致静默失败
真正麻烦的不是裁剪本身，而是平台差异带来的路径、像素、DOM、API 行为不一致——每个环节都要做守卫、降级、验证，漏一个就卡在真机上动不了。
