cropper.js初始化图片不显示或黑屏，主因是容器无显式宽高或图片未加载完就初始化；必须用img.onload确保加载完成后再new cropper，且容器需设width/height，避免display:none父元素中初始化。
cropperjs 初始化时图片不显示或黑屏
常见原因是容器没有显式宽高，或者图片加载完成前就初始化了 Cropper 实例。Cropper.js 不会自动等待图片加载，必须确保 <img> 的 src 已加载完毕再执行 new Cropper()。
- 用
img.onload回调初始化，而不是 DOM 加载完就调用 - 容器（如
<div id="cropper-container">）必须设 <code>width和height，不能依赖内容撑开 - 避免在
display: none的父元素里初始化；若需隐藏，改用visibility: hidden或初始化后再隐藏 - 若用 webpack/vite 加载图片，注意静态资源路径是否正确，控制台报 404 会导致
onload不触发 - 初始化时至少设
rotatable: true, scalable: true, zoomable: true - 旋转要用
cropper.rotate(degree)，不是设置属性；推荐用按钮触发，例如：document.getElementById('rotate-right').onclick = () => cropper.rotate(90) - 缩放建议用
cropper.zoom(ratio)（正数放大，负数缩小），而非直接改scaleX/scaleY—— 后者绕过 Cropper 内部状态管理，易导致裁剪框错位 - 注意：
zoomable: true仅启用鼠标滚轮缩放；拖拽缩放（如 pinch 手势）需额外引入cropperjs-touch插件 - 务必使用
getCroppedCanvas().toBlob(callback, 'image/jpeg', 0.8)，不要省略第三个参数（质量值），否则 PNG 透明通道可能被错误处理 - 如果旋转角度非 90° 倍数，
getCroppedCanvas()返回的 canvas 可能比预期大（含留白），需用getCroppedCanvas({ width: 800, height: 600 })显式指定输出尺寸 - 某些浏览器（如旧版 Safari）对跨域图片调用
toBlob会静默失败，此时检查控制台是否有Failed to execute 'toBlob' on 'HTMLCanvasElement'错误，解决方案是给<img>加crossOrigin="anonymous"并确保服务端返回Access-Control-Allow-Origin - 必须引入官方扩展
cropperjs-touch（单独的 JS 文件，非 npm 子包），且要在Cropper构造函数之后加载 - 初始化时加
responsive: true, restore: false，避免 resize 时重置旋转/缩放状态 - 安卓 WebView 中可能出现 touchstart 被拦截，检查父容器是否设置了
touch-action: none；如有，改为touch-action: pan-x pan-y pinch-zoom - 真机调试时发现缩放卡顿？关闭
checkCrossOrigin: false（默认为 true）可减少跨域校验开销，但前提是图片同源或已配好 CORS
启用旋转和缩放功能需要哪些关键配置
Cropper 默认禁用旋转和缩放，必须显式开启并绑定 UI 操作。核心是 rotatable、scalable 和 zoomable 三个布尔选项，且需配合事件监听手动调用实例方法。
获取裁剪结果时 canvas.toBlob() 返回空或黑图
这是最常踩的坑：调用 cropper.getCroppedCanvas() 后未等 canvas 渲染完成就导出，尤其在旋转后 canvas 需要重绘时间。
移动端 touch 交互失效或响应迟钝
Cropper.js 原生只支持鼠标事件，移动端需补全 touch 支持，否则拖拽裁剪框、双指缩放都不可用。
getCroppedCanvas() 输出的像素数据与原始图片尺寸不再线性对应，如果后续要做人脸识别或 OCR，必须用 cropper.getData() 获取当前 transform 状态，而不是硬编码比例换算。
