layui upload 组件不支持圆形裁剪，因其仅负责文件选择与上传，无图像处理能力；所谓“圆形裁剪”实为 cropper.js 正方形裁剪（aspectratio: 1）配合 css 圆角遮罩实现，后端接收的仍是矩形图片。
layui 原生 upload 组件不支持圆形裁剪，必须在上传前用 cropper.js 或封装版 croppers.js 手动控制裁剪逻辑，并显式设置 aspectratio: 1 和 viewmode: 1 等参数模拟圆形效果——本质是正方形裁剪 + css 圆角遮罩，而非真圆裁剪。
为什么 layui upload 无法直接做圆形裁剪
upload 只负责文件选择和提交，裁剪属于图像处理范畴，它本身没有 canvas 渲染、坐标计算或 mask 裁剪能力。所谓“圆形裁剪”，实际是前端用 cropper.js 限制裁剪框为正方形（aspectRatio: 1），再配合 CSS border-radius: 50% 视觉遮罩，后端收到的仍是矩形图片数据。
常见错误现象：
- 配置了
accept: 'images'就以为能裁剪 —— 实际只是过滤文件类型，无裁剪行为 - 在
done回调里调用cropper—— 此时文件已发往服务端，本地只剩返回 URL，无法再操作原始像素 - 没设
auto: false，导致文件选中后立刻上传，根本没机会初始化 cropper 实例
用 croppers.js 实现“伪圆形裁剪”的关键参数
社区常用封装版 croppers.js（非官方）支持快速接入，但需注意它默认输出的是矩形图，要视觉上像圆形，得靠容器样式+裁剪约束：
-
aspectRatio: 1：强制裁剪区域宽高比为 1:1，得到正方形画布 -
viewMode: 1：限制图片不能被拖出裁剪框外，避免空白边干扰 -
dragMode: 'move'：关闭缩放模式，防止用户误操作打乱比例 - HTML 容器加
style="border-radius: 50%; overflow: hidden;"，让预览图显示为圆形 - 后端无需特殊处理，接收的仍是标准 PNG/JPEG 文件，只是内容为居中正方形区域
示例片段：
croppers.render({
elem: '#uploadBtn',
url: '/api/upload-avatar',
saveW: 200,
saveH: 200,
aspectRatio: 1,
viewMode: 1,
dragMode: 'move',
done: function(res) {
$('#avatar').attr('src', res.data.src).css('border-radius', '50%');
}
});
用原生 cropper.js 手动控制更可靠
放弃封装版，自己串联流程，能避开参数兼容问题，也更容易干预输出格式（比如强制 JPEG + 压缩）：
- 在
choose回调里读取obj.files[0]，用FileReader转成dataURL - 把
dataURL注入到已挂载的<img>元素，再初始化cropper实例 - 用户点击“确认裁剪”后，调用
cropper.getCroppedCanvas().toBlob()得到 Blob - 用
upload.post()提交该 Blob，而非原始文件 - 若需真正圆形像素图（非遮罩），得用
canvas手动绘制圆形 mask，但多数业务场景不需要
关键代码节选：
upload.render({
elem: '#uploadBtn',
auto: false,
choose: function(obj) {
const file = obj.files[0];
const reader = new FileReader();
reader.onload = function(e) {
$('#crop-img').attr('src', e.target.result).cropper({
aspectRatio: 1,
viewMode: 1,
crop: function(e) { /* 可选：实时预览裁剪区域 */ }
});
};
reader.readAsDataURL(file);
},
// 注意：这里不设 url，改由手动 post
});
真正难的不是“怎么画圆”，而是确保裁剪时机卡在文件选中后、上传前这个窄窗口；很多人卡在 DOM 渲染顺序或 cropper 初始化时机上，比如 #crop-img 还没插入文档就调 .cropper()，报 Cannot read property 'cropper' of undefined——这种错没法靠改配置解决，只能检查元素是否存在、是否可渲染。
