HTML中利用Canvas API捕获预览画面实时快照并生成缩略图

在前端开发中，使用 Canvas API 截取视频（Video）元素中的画面是一项常见需求。然而，许多开发者会遇到这样的困扰：视频明明在正常播放，但调用 drawImage 后却只得到全黑或空白的图像。别担心，这背后通常有几个明确的“陷阱”，逐一排查即可解决。

Canvas drawImage 捕获 video 元素画面时黑屏怎么办

直接调用 drawImage 却得到全黑或空白图像，大概率是因为视频尚未加载完成、未开始播放或未满足 canvas 的捕获条件。video 必须处于“可绘制状态”：已加载元数据（loadedmetadata）、至少解码了一帧（canplay 或 playing），并且不能是跨域资源（否则会污染 canvas）。

实操建议：

• 建议监听 video 元素的 loadeddata 事件后再执行首次 drawImage，这比 loadedmetadata 更加可靠，因为数据已加载到足够播放的帧。
• 对于外部 URL 的视频源，务必在 video 标签上设置 crossOrigin="anonymous" 属性，否则即使视频加载成功，canvas 也会因跨域污染而被禁止读取。
• 部分浏览器会阻止静音自动播放（autoplay）下的 canvas 读取，因此在用户未交互（如点击）时尝试捕获可能失效。请确保视频已开始播放或用户已触发交互。
• 通过检查 video.readyState 是否大于等于 2（HAVE_CURRENT_DATA）来判断是否可绘制，可以使用 setInterval 轮询或监听 timeupdate 事件。

缩略图尺寸与 canvas 像素比不匹配导致模糊或拉伸

Canvas 绘制时不会自动缩放像素，drawImage 的目标宽高若与 canvas 的 width/height 属性不一致，浏览器会通过插值缩放，导致图像失真。常见错误是只设置了 CSS 样式的宽高，却未同步更新 canvas 的 DOM 属性。

实操建议：

• 明确设置 canvas 元素的 width 和 height 属性（而不是 CSS 样式），例如：canvas.width = 160; canvas.height = 90;。
• 若需保持宽高比缩放，先计算目标尺寸：const scale = Math.min(160 / video.videoWidth, 90 / video.videoHeight);，再传入 drawImage(video, 0, 0, video.videoWidth * scale, video.videoHeight * scale)。
• 避免使用 ctx.scale() 代替精确尺寸计算，因为它会影响后续所有绘制操作，且容易累积误差。
• 对于高清预览缩略图（如用作封面），建议 canvas 尺寸不低于 320×180，然后通过 CSS 缩小显示，以保留清晰度。

生成 Data URL 后无法下载或显示为空白

调用 canvas.toDataURL() 返回空字符串或损坏的 base64，通常是由于 canvas 被污染（tainted canvas），即曾绘制过跨域但未声明 crossOrigin 的视频或图片；也可能是调用时机过早（视频未就绪）或 canvas 尺寸为 0。

实操建议：

• 确认 video 元素设置了 crossOrigin="anonymous"，并且服务端响应头包含 Access-Control-Allow-Origin: *（或指定域名）。
• 不要在设置 video.src 后立即调用 toDataURL，必须等待 loadeddata 或 playing 事件触发后再执行。
• 检查 canvas 的 width 和 height 是否为正整数——若为 0 或 NaN，toDataURL 必然返回空字符串。
• 如需导出 PNG 格式（默认是 JPEG），显式传参：canvas.toDataURL('image/png', 1.0)；JPEG 可添加质量参数（0.1–1.0）来控制文件体积。

高频截图导致性能卡顿或内存泄漏

频繁执行 drawImage 和 toDataURL（如每秒多次）会迅速积累 bitmap 数据，尤其在移动设备上容易引发垃圾回收（GC）停顿甚至内存溢出（OOM）。并非所有场景都需要逐帧截图——缩略图通常只需关键帧或间隔采样。

实操建议：

• 使用 requestAnimationFrame 替代 setInterval 控制捕获节奏，这样自然与屏幕刷新率同步。
• 限制最小捕获间隔，例如每 500ms 最多捕获一次：if (Date.now() - lastCapture > 500) { capture(); lastCapture = Date.now(); }。
• 复用同一个 canvas 和 2D context，避免反复创建新对象；toDataURL 后无需清空 canvas，但若后续绘制不同内容，应调用 ctx.clearRect(0, 0, w, h)。
• 如果只需要缩略图 URL 而不是立即使用，可以考虑使用 canvas.toBlob(callback, type, quality)，避免 base64 字符串的内存开销。

Canvas 污染问题是最隐蔽且最难排查的故障，一旦发生，整个 canvas 会变成“只写”状态——连 getImageData 都会报错。因此，务必在视频加载阶段就确认 crossOrigin 配置正确生效，而不是等到截图失败后才开始排查。