uni.chooseImage无法获取裁剪后图片，因其仅支持选图不支持裁剪；需搭配uni-cropper等插件实现裁剪，注意H5兼容性、比例锁定、base64上传限制及临时文件路径规范。

uni-app 里用 uni.chooseImage 拿不到裁剪后图片

因为 uni.chooseimage 只负责选图，不带裁剪能力。直接调它返回的是原始文件路径或临时地址，和裁剪完全无关。

常见错误现象：tempFilePaths[0] 显示一张大图，上传后发现没裁、比例错、甚至黑边——本质是跳过了裁剪环节。

• 必须搭配专门的裁剪组件或插件，比如 uni-ui 的 uni-cropper，或社区较稳定的 we-cropper（需自行适配 uni-app）
• 不能在 success 回调里直接传 tempFilePaths[0] 给上传逻辑，得等裁剪完成回调再取结果
• uni-cropper 返回的是 base64 字符串（默认），不是文件路径；若后端要 file 表单上传，得先用 uni.getFileSystemManager().writeFile 转成临时文件

uni-cropper 配置宽高比失效或裁剪框拉伸变形

根本原因是容器尺寸未固定，或父级元素用了 flex / 百分比布局，导致裁剪画布计算错乱。

使用场景：头像裁剪（1:1）、封面图（16:9）等需要强约束比例的场合。

• 确保 uni-cropper 的父容器有明确的 width 和 height（推荐用 px 或 rpx，避免 %）
• scaleRatio 参数只控制缩放倍数，不影响裁剪比例；真正锁定比例靠 aspectRatio，例如头像设为 1，封面设为 16/9
• 安卓真机上如果开启 useScale，可能触发 canvas 渲染异常，建议关闭；iOS 则相对稳定

裁剪后上传失败：base64 过长 or 临时文件不存在

base64 直接传给后端接口，容易超长（尤其高清图），而部分服务端对请求体有限制；转临时文件又常因路径写错或时机不对失败。

性能影响：一张 2MB 原图裁成 500×500，base64 约 700KB，HTTP 请求体膨胀明显；转临时文件虽绕路，但更稳妥。

• 优先走「base64 → 后端 base64 解码」路径，但务必确认后端支持（如 PHP 的 base64_decode，Node 的 Buffer.from(data, 'base64')）
• 若必须传文件，用 uni.getFileSystemManager().writeFile 写入时，filePath 必须是 uni.env.USER_DATA_PATH 下的路径，且扩展名要手动补全（如 .png）
• 别在 onLoad 里提前调裁剪，确保 uni.chooseImage 成功返回后再初始化 uni-cropper，否则 src 为空会导致 write 失败

H5 平台下 uni-cropper 报错 canvas is not defined

这是 H5 编译时 canvas 环境未正确注入导致的，非代码写错，而是平台适配缺失。

兼容性影响：微信小程序、App 正常，唯独 H5 报这个错，且页面白屏或卡死。

• 检查 vue.config.js 是否配置了 configureWebpack，并加入了 canvas polyfill（如 canvas npm 包）——但 uni-app 官方不推荐，易引发其他冲突
• 更可靠的做法：H5 下改用纯 JS 裁剪库（如 cropperjs），通过 uni.createSelectorQuery() 获取 DOM 节点后手动初始化
• 注意 cropperjs 的 ready 回调时机比 uni-cropper 晚，上传逻辑得包在它里面，不能依赖 mounted

实际集成时最麻烦的不是调用哪个 API，而是裁剪结果如何与你现有的上传链路对齐——base64 怎么解、临时文件怎么删、失败后怎么重试，这些细节没串起来，插件再好也白搭。