在前端开发中，使用 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 配置正确生效，而不是等到截图失败后才开始排查。
