video 的 poster 属性必须为可访问的 http/https 网络 url,不支持本地路径;需配合 preload="metadata" 和有效 src 才能显示;播放结束后需手动监听 ended 事件恢复封面。

poster 属性设不对,封面根本不会出现——不是图片路径错,而是它和视频加载状态强绑定,且只认网络地址、不支持本地相对路径。
video 的 poster 必须是可访问的网络 URL
uniapp 和多数 WebView 环境(包括 iOS Safari、微信内置浏览器)中,poster 仅接受以 http:// 或 https:// 开头的完整 URL。哪怕你把图片放在 /static/cover.jpg,直接写 poster="/static/cover.jpg" 也会静默失败。
- 本地开发时可用
https://localhost:8080/static/cover.jpg临时验证,但上线必须走真实 CDN 或服务器域名 - uniapp 中推荐用
uni.uploadFile预上传封面图,拿到返回的tempFilePath后再拼成线上地址赋给poster - 不要用
require('./cover.jpg')或import cover from './cover.jpg'—— 这些在poster属性里完全无效
poster 不显示?先检查 preload 和 src
poster 不是独立渲染的“背景图”,它的显示依赖视频元数据是否开始加载。如果 src 为空、404、跨域或格式不被支持,poster 就不会浮现。
- 务必设置
preload="metadata":它只请求视频头信息(几 KB),不下载主体,既快又省流量;preload="auto"在移动端常被忽略或触发拦截 -
src必须指向一个能实际HEAD成功的视频地址——哪怕只是占位 MP4 文件(1KB 空壳也行),否则浏览器认为“无资源可加载”,poster直接跳过 - uniapp 中若用变量绑定
:src,确保该变量初始值非空字符串或null,否则组件初始化阶段就卡住加载逻辑
别用 CSS background-image 模拟 poster
虽然加个 div 包着 video 再用背景图能“看起来像”封面,但这会破坏原生控件行为:
- 全屏按钮点击后,只放大
video元素本身,背景图被裁掉或错位 - 音量条拖动、进度条点击等交互区域可能偏移,尤其在横竖屏切换时
- iOS 微信里,
background-image在video上层时,会拦截click事件,导致无法点播
复杂点在于:播放结束后的“伪封面”得手动接管
poster 只在加载前生效,播放结束后它不会自动回来。想实现“播完显示封面”,得监听 ended 事件并用 JS 控制显隐:
<video :poster="posterUrl" :src="videoUrl" controls preload="metadata"><source :src="videoUrl" type="video/mp4"></source></video><img v-if="showEndPoster" :src="posterUrl" class="end-poster">
这里 showEndPoster 是响应式变量,onVideoEnd 里设为 true;同时注意,某些安卓 WebView 对 ended 事件触发不及时,建议加 100ms 延迟再更新状态。










