HTML5视频截图与Canvas保存教程

本文详解HTML5中从video元素截取视频帧并保存为图片的核心技术要点，重点揭示了跨域安全策略（CORS）和Canvas缓冲区尺寸设置这两大高频“踩坑点”：必须为video添加crossOrigin="anonymous"属性、确保服务端正确配置Access-Control-Allow-Origin头，同时严格区分canvas的CSS显示尺寸与实际绘图缓冲区尺寸，通过video.videoWidth/Height动态设置canvas.width/height，并在video加载完成（loadeddata事件）后调用ctx.drawImage()安全绘制；还提供了toDataURL()兼容性处理、JPEG fallback、Blob下载等实用方案，助你避开黑屏、报错、模糊、静默失败等常见问题，真正实现稳定可靠的前端视频截图功能。

video 元素没加 crossOrigin 属性，toDataURL() 直接报错

Canvas 从 video 截图本质是「读取视频帧像素」，而浏览器默认禁止跨域视频的像素读取。哪怕视频在同域，用 file:// 协议打开、或视频由 CDN 提供（如 mp4 链接带域名），都可能触发 CORS 策略拦截。

常见错误现象：Failed to execute 'toDataURL' on 'HTMLCanvasElement': Tainted canvases may not be exported.

• 给 加上 crossOrigin="anonymous" 属性（注意不是 "use-credentials"）
• 确保视频服务器返回了 Access-Control-Allow-Origin: * 或对应源（CDN 一般支持配置）
• 本地开发时别用双击打开 HTML 文件，改用 python3 -m http.server 或 VS Code Live Server 启动服务

canvas.drawVideo() 不存在 —— 正确调用是 ctx.drawImage()

很多人搜 “video 截图” 会误以为有专用函数，其实所有操作都走 Canvas 2D 上下文的通用绘图方法。关键在于时机：必须等视频有画面帧可读，不能一加载完就画。

使用场景：用户点击按钮截当前帧、自动定时截图、播放暂停后截图

• video.readyState >= HTMLMediaElement.HAVE_CURRENT_DATA 是安全绘制的前提
• 推荐监听 video 的 loadeddata 事件后再首次截图，避免黑屏
• 示例代码片段：

  const canvas = document.getElementById('myCanvas');
  const ctx = canvas.getContext('2d');
  ctx.drawImage(video, 0, 0, canvas.width, canvas.height);

截图模糊或尺寸不对，多半是 canvas 宽高没设对

Canvas 的显示大小（CSS width/height）和实际绘图缓冲区大小（canvas.width/canvas.height）是两回事。直接用 CSS 缩放会导致像素拉伸、模糊，且 toDataURL() 输出的是缓冲区原始分辨率。

性能影响：缓冲区过大（比如设成 1920×1080）但只显示 320×180，内存和编码开销明显上升

• 用 video.videoWidth 和 video.videoHeight 获取真实帧尺寸
• 显式设置 canvas.width = video.videoWidth，canvas.height = video.videoHeight
• 如果需要缩略图，先按比例算出目标宽高，再传给 drawImage() 的第 5–6 个参数（目标宽高），而非改 canvas 自身尺寸

保存为图片失败？toDataURL() 返回空字符串或 MIME 类型不匹配

toDataURL() 默认生成 image/png，但部分老旧安卓 WebView 或 iOS Safari 在某些视频编码下可能不支持 PNG 导出，返回空字符串；也有时因 canvas 被污染（CORS 未配好）而静默失败。

兼容性影响：iOS 15.4+ 对 HEVC 视频的 canvas 绘制支持仍不稳定，优先用 H.264

• 加上 try/catch 捕获异常，并 fallback 到 image/jpeg：

  try {
    const url = canvas.toDataURL('image/jpeg', 0.9);
  } catch (e) {
    console.error('截图失败:', e);
  }

• 生成 URL 后，用 URL.createObjectURL() 创建 blob URL 再赋给 下载，比直接 window.open 更可靠
• 注意：Safari 对 download 属性支持有限，移动端基本不可用，建议提示用户“长按图片保存”