必须处理 uni.chooseImage 的权限与平台差异：iOS 需配置「相册」权限，Android 需「读取外部存储」和「相机」，H5 须条件编译改用 input[type="file"]；上传前需校验文件类型、尺寸及 HTTPS 地址；上传后须同步更新状态、缓存与云数据库。
点击头像触发 uni.chooseImage 时权限和平台差异必须处理
真机调试时 iOS 或 Android 可能直接静默失败，不弹提示也不报错——根本原因是没在 manifest.json 配置对应权限。H5 端则压根不走原生相册逻辑，而是用 input[type="file"] 模拟，行为不一致。
实操建议：
- iOS 需在
manifest.json → App SDK 配置 → 权限配置勾选「相册」；Android 要勾选「读取外部存储」和「相机」（即使只选图，部分厂商 ROM 也会校验） - H5 端无法调用
uni.chooseImage，需用条件编译：#ifdef H5分支改用并监听change事件 - 所有平台都建议加
sourceType: ['album', 'camera']显式声明，避免某些安卓机型默认只开相机
uni.uploadFile 上传前必须做文件类型和尺寸校验
用户可能选了超大图（比如 8MB 的原图）或非图片格式（如 .pdf），后端接口常会直接 400 或超时，但前端没反馈，体验断层。
实操建议：
- 用
uni.getImageInfo提前读取宽高和size（单位字节），拦截 >2MB 或宽高 >2000 的图 - 检查
res.type是否以image/开头，防止绕过 input 的 accept 限制上传非图文件 - 上传时
url必须是完整 HTTPS 地址（H5 和小程序都强制），且后端接口要支持 multipart/form-data，字段名（如file）需与后端约定一致 - 别漏掉
header：登录态 token 通常要塞进Authorization或自定义字段，否则 401
上传成功后如何安全更新头像 URL 并持久化
常见错误是只改了页面上的 avatarUrl 变量，但没同步到 vuex / pinia，也没调用 uni.setStorageSync，切页再回来头像就回退了。
实操建议：
- 后端返回的头像地址，优先使用其返回的完整 URL（如
https://xxx.com/uploads/abc.jpg），不要自己拼接域名 - 立即更新本地状态：Vue 3 中用
ref或store.avatar = res.data.url；同时调用uni.setStorageSync('user_info', { ...userInfo, avatar: res.data.url }) - 如果项目用了
uni-id，记得调用uniCloud.callFunction更新云数据库里的user.avatar字段，否则下次登录还是旧头像 - 上传中加 loading 状态（
isUploading = true），按钮禁用并显示「上传中…」，避免重复点击触发多请求
小程序端头像裁剪不是必须的，但用户预期存在
微信/支付宝小程序的 uni.chooseImage 不带裁剪能力，用户选完图直接上传，方形头像会被拉伸。虽然技术上可以跳转到自定义裁剪页（用 canvas 绘制），但多数场景没必要增加复杂度。
实操建议：
- 如果设计稿明确要求圆形/方形头像，后端应统一返回裁剪后的 URL（比如加参数
?x-oss-process=image/resize,m_fill,h_200,w_200），前端只负责展示 - 真要做前端裁剪，推荐用现成库如
vue-cropper（H5）或小程序原生组件movable-view+canvas，但注意 canvas 在 iOS 小程序里导出 base64 性能差，建议导出临时路径再上传 - 别在
success回调里直接this.avatarUrl = tempFilePaths[0]—— 这是本地临时路径，仅本次有效，上传完成前不能当最终头像用
实际最难的不是调 API，是把「用户点一下→看到新头像」这个链路里每个环节的异常都兜住：权限拒绝、选图取消、网络中断、后端校验失败、token 过期、缓存未更新……这些地方少一个 catch 或 else 分支，用户就会卡在“好像点了，但没反应”。
