poster属性仅支持同源静态图片路径,不支持网络地址、空字符串或Data URL;本地file://协议下失效;需确保HTTP 200响应及正确MIME类型(image/jpeg或image/png),推荐使用相对路径且尺寸匹配视频分辨率。

poster 属性必须是绝对或相对有效路径
HTML5 的 poster 不会加载网络地址(如 https:// 开头)或空字符串,也不支持 Data URL(多数浏览器会静默忽略)。它只接受页面同源的静态资源路径,且该图片必须能被浏览器直接 HTTP GET 访问到。
常见错误现象: 在本地双击打开 HTML 文件时失效——因为 file:// 协议下浏览器禁止加载本地图片作为 poster;部署后仍不显示,大概率是路径 404 或 MIME 类型不对(如服务器返回 text/plain 而非 image/jpeg)。
- 用浏览器开发者工具 Network 面板过滤
Img,确认 poster 请求状态码为 200,且Content-Type是image/* - 路径优先用相对路径(如
./images/cover.png),避免../跨级导致错位 - 不要写成
poster="./cover.jpg?"带无意义查询参数——部分旧版 iOS Safari 会拒绝加载
移动端 Safari 对 poster 尺寸和格式有隐性要求
iOS 15+ 和 iPadOS 中,如果 poster 图片宽高比与 的 width/height 或 CSS 设置严重不匹配,Safari 可能渲染空白或拉伸失真。同时,WebP 格式在 iOS 16 之前完全不支持作为 poster。
- 推荐尺寸:与视频原始分辨率一致(如视频是 1280×720,poster 也用 1280×720)
- 格式限定为
.jpg或.png,避免.webp、.avif - 若用 CSS 控制尺寸(如
width: 100%; height: auto;),确保父容器有明确宽度,否则 poster 可能塌陷为 0×0
poster 在 autoplay 失败时可能被跳过
Chrome、Edge 等现代浏览器对自动播放有严格策略:无用户交互(如点击)前提下,带声音的视频即使设了 autoplay 和 poster,也可能直接黑屏等待触发——此时 poster 不会显示,直到用户首次交互或静音后重试。
立即学习“前端免费学习笔记(深入)”;
- 加
muted属性可提升 autoplay 成功率: - 不要依赖 poster 作为唯一首帧提示:可在
外层加一层作为 fallback 封面,并用 JS 监听loadedmetadata事件后移除- 测试时禁用广告拦截插件——某些插件会误杀 poster 请求(表现为 Network 中 poster 显示 “Blocked”)
JS 动态设置 poster 需等元素挂载完成
通过 JS 设置
video.poster = "path.jpg"无效,常见于 Vue/React 组件中 DOM 尚未插入文档就执行赋值,或使用了document.write等破坏性操作。- 在
DOMContentLoaded或组件mounted钩子中设置 - 设置后可手动触发一次
video.load()强制重新解析资源(尤其在切换 poster 时) - 注意:动态设置 poster 不会触发
loadstart,但会重置视频当前时间、暂停状态
image/jpeg,iOS Safari 就当它不存在。










