移动端字幕不显示的根本原因是浏览器未加载轨道,需确保其为直接子元素且紧接后,四属性齐全(kind、srclang、label、src),WebVTT格式正确,服务器返回text/vtt类型,并等待track.readyState===2再操作。

移动端字幕不显示?先确认
绝大多数移动端字幕失效,根本不是 JS 或样式问题,而是浏览器压根没把 当作有效轨道加载——iOS Safari 和旧版 Android WebView 会静默忽略位置错误、属性缺失或 MIME 类型不对的轨道,连控制台都不报错。
-
必须是的**直接子元素**,且**紧接在所有之后**;写在前、包在里、或跟之间多一个换行,都会被 Safari 完全跳过- 四个属性缺一不可:
kind="subtitles"(不能是caption或漏写)、srclang="zh"(必须是 ISO 639-1 码,zh-Hans在部分安卓 WebView 中不识别)、label="中文"(空值或未设会导致菜单不出现)、src="zh.vtt"(路径需可访问,跨域需 CORS)- 移动端不响应
default属性:iOS Safari 默认隐藏字幕按钮,且即使写了default,首次加载也大概率不启用;别依赖它自动开WebVTT 文件在手机上打不开?检查这三点硬性条件
用手机浏览器地址栏直接访问
yourdomain.com/zh.vtt,如果看到乱码、空白页或下载弹窗,说明文件本身没过关。移动端对格式更敏感,容错几乎为零。- 首行必须是顶格、全大写、无空格、无 BOM 的
WEBVTT;VS Code 右下角编码选“UTF-8”而非“UTF-8 with BOM”,保存时确认无隐藏字符 - 时间戳严格为
00:00:01.234 --> 00:00:04.567:小时/分钟/秒两位,毫秒三位,-->两侧各一个空格;SRT 序号行(如1)、空行、中文标点都会导致解析失败 - 服务器必须返回
Content-Type: text/vtt;Nginx 配置加types { text/vtt vtt; },Apache 加AddType text/vtt .vtt;用 curl -I 检查响应头,不是text/plain或application/octet-stream
JS 控制字幕在 iOS 上无效?因为 readyState 还没到 2
直接写
track.mode = "showing"在 iOS Safari 里经常白忙活——字幕文件还在加载中,track.readyState是 0(TextTrack.NONE)或 1(TextTrack.LOADING),设了也无效。- 必须等
track.readyState === 2(即TextTrack.LOADED)再操作;推荐监听track.onload事件,比轮询更可靠 - 动态添加
后,video.textTracks列表虽立刻更新,但对应track对象的readyState仍为 0,需等加载完成才能控制 - 别用
video.subtitleEnabled——这个属性根本不存在,MDN 和 Chrome DevTools 都不认
原生字幕控件在手机上不可用,那就自己做开关
iOS Safari 不显示字幕按钮,Android 7.0 以下 WebView 甚至不触发
textTracks列表;指望用户点右下角“CC”图标是不现实的,必须主动提供 UI 并接管逻辑。- 用
实现语言切换,点击后遍历video.textTracks,匹配srclang,设目标mode = "showing",其余设"disabled" - 初始化时先检查
video.textTracks.length === 0,若为空,说明轨道加载失败,立即 fallback 到+ JS 解析 VTT 内容并定时渲染- 移动端字幕层建议用
position: absolute; bottom: 20px;+pointer-events: none;,避免遮挡手势操作;CSS 用backdrop-filter: blur(2px)提升可读性(iOS 15+ 支持)真实兼容性断层就在这里:不是你代码写得不够好,而是 iOS 和旧安卓 WebView 对
的实现差异太大,必须按设备能力分层处理。漏掉任意一个检查点,字幕就会彻底消失,而且毫无提示。 - 移动端字幕层建议用
- 四个属性缺一不可:
前端入门到VUE实战笔记:立即使用
在学习笔记中,你将探索 前端 的入门与实战技巧!











