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

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



















