如何用HTML Canvas实时快照生成预览缩略图

在实际的开发场景中，使用 Canvas API 捕获 Video 元素中的画面是一个常见需求。但不少开发者会碰到这样的问题：明明视频在播放，调用 drawImage 之后，得到的却是一张全黑或空白的截图。别着急，这背后通常有几个明确的“坑”，逐个解决就能顺利实现。

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

直接调用 drawImage 却得到全黑或空白图像，大概率是 video 还没有加载完成、没有播放，或未满足 canvas 捕获的前提条件。video 必须处于「可绘制状态」：已加载元数据（loadedmetadata），至少一帧已解码（canplay 或 playing），且不能是跨域资源（否则会触发 canvas 污染）。

实操建议：

• 监听 video 的 loadeddata 事件后再首次调用 drawImage，比 loadedmetadata 更可靠。
• 确保 video 元素设置了 crossOrigin="anonymous"（如果源为外部 URL），否则即使加载成功也会因污染被拒绝读取。
• 避免在 autoplay 未生效或用户未交互（如点击）时尝试捕获——部分浏览器会阻止静音 autoplay 下的 canvas 读取。
• 检查 video.readyState ≥ 2（HA VE_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 的视频或图片；也可能是调用时机过早（video 未就绪）或 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 都会抛出错误。务必在 video 加载阶段就验证 crossOrigin 设置是否生效，而不是等到截图失败才排查。