必须自研 canvas 拼图逻辑，因极验等 SDK 依赖浏览器 API，在小程序/App 报错且 H5 易事件失效；需用 uni.createCanvasContext 绘制同源同尺寸图片，clip 或 globalCompositeOperation 实现缺口，归一化上报 offset、token、timestamp 等字段。
不能直接用 web sdk，必须自己用 touchstart/touchmove/touchend + canvas 重写核心逻辑，后端生成并下发缺口坐标、背景图和缺口图，前端只负责渲染与上报偏移量。
为什么不能直接引入极验或腾讯云的 JS SDK
这些 SDK 依赖 window、document、addEventListener 等浏览器 API，在小程序和 App 端运行会直接报错：ReferenceError: window is not defined 或 Cannot read property 'appendChild' of null。H5 环境下也可能因根节点不是 document.body 导致事件委托失效，拖拽无响应。
常见错误现象：
- 真机调试时组件空白，控制台报 DOM 相关错误
- H5 页面能加载但滑块无法拖动或松手后不触发验证
- 小程序里
new Image()失败，图片不显示
如何用 canvas 正确绘制拼图和背景图
不能靠 CSS 定位 image 标签模拟缺口——缩放、裁剪、像素对齐全不可控。必须用 uni.createCanvasContext 手动绘制，且两张图必须同源、同尺寸、同比例缩放，否则后端校验像素级偏移会失败。
关键实操点：
- 先调用
uni.getImageInfo获取背景图和缺口图的真实宽高，避免 canvas 绘制拉伸 - 绘制顺序：先
drawImage背景图 →clip()切出缺口矩形 → 再drawImage缺口图（仅显示在裁剪区内） - iOS 真机上
clip()可能失效，可改用globalCompositeOperation = 'destination-out'配合透明矩形“擦除”背景来模拟缺口 - 安卓真机加载网络图易失败，应先用
uni.downloadFile缓存到本地临时路径再传入drawImage - canvas 的
width和height属性必须显式设置（不能只靠 CSS），否则 H5 和小程序渲染不一致
如何计算和上报用户拖动偏移
滑块初始位置要和缺口左上角对齐（注意：缺口图 X 坐标是后端返回的 cutX，但滑块自身有宽度，比如 40px，所以滑块 left 应设为 cutX - 40）。拖动时只更新 left 值，不重绘 canvas；松手时归一化上报，不是原始像素值。
示例归一化计算（防浮点误差 + 限范围）：
const maxWidth = 280; // 背景图可拖动最大宽度（px） const offsetX = Math.max(0, Math.min(touchX - sliderLeft, maxWidth)); const normalized = parseFloat((offsetX / maxWidth).toFixed(3)); // 保留三位小数
必须上报的参数（后端校验所必需）：
-
normalized：归一化后的偏移比例（0～1） -
token或captchaId：本次验证唯一标识，由后端生成并随图片一起下发 -
timestamp：客户端时间戳，用于风控（如滑动耗时过短可能被判定为机器） - 设备指纹字段（如
platform、model、screenWidth）可选，增强反刷能力
后端返回哪些字段才算完整可用
前端拿到的每一套验证数据，必须包含以下四项，缺一不可：
-
backgroundImg：背景图 URL 或 base64（建议优先 base64，规避跨域和加载失败） -
sliderImg：缺口图（即被挖下来的那一小块），必须与背景图同源同次生成 -
cutX：缺口左上角在背景图中的 X 坐标（单位 px），前端用于定位滑块起始位置和后端校验基准 -
cutY：缺口 Y 坐标（单位 px），前端用于 canvas 中垂直对齐，否则拼图错位
容易被忽略的关键点：所有字段都必须绑定本次请求会话（如手机号、token、IP、UA），不能复用同一套图多次验证，否则 A 用户滑出的 offset 可被 B 用户直接提交绕过。后端保存的“正确答案”是 cutX，不是前端计算出的 left，两者差值要在容差范围内（通常 ±5px）才视为通过。
