首先，我们来梳理几个常见的坑点：video 标签中的 必须紧跟在所有 之后，并且严格位于 内部；WebVTT 字幕文件需要满足首行 WEBVTT、UTF-8 无 BOM、标准时间戳格式以及 text/vtt MIME 类型；使用 JavaScript 控制字幕轨道时，必须等到 track.readyState 变为 2 才能操作；在移动端，最好自行设计 UI 并准备一个模拟字幕层作为 fallback。下面逐一详细说明。

video 标签内 放置顺序错误会导致失效

浏览器只识别 开始标签之后、 之前，且必须紧跟在所有 之后的 。以下常见错误都会让字幕无法加载：

• 将 放在 前面
• 将其放到 外面，即使只多一个换行符
• 包裹在

  或注释中

• 多个 之间夹杂了空标签或 HTML 注释

这些操作都会导致浏览器直接忽略，既不报错也不加载，最终字幕区域一片空白。

WebVTT 文件必须满足四个硬性条件

仅修改后缀名为 .srt 并不能直接转换。一份合格的 .vtt 文件必须满足以下四条要求：

• 首行严格为 WEBVTT（全大写，无空格，无 BOM 头）
• 编码为 UTF-8 无 BOM（在 VS Code 右下角选择“Save with Encoding” → UTF-8）
• 时间戳格式为 00:00:01.234 --> 00:00:04.567，不能包含 SRT 的序号行或者空行分隔
• 服务器返回头信息 Content-Type: text/vtt（Nginx/Apache 需要手动配置 MIME 类型）

遗漏任意一条，Chrome 和 Firefox 都会静默失败，连错误提示都不会给出。

JS 控制字幕前必须等待 track.readyState === 2

直接设置 track.mode = "showing" 很可能无效——因为字幕文件尚未加载完成。浏览器不会主动等待。正确的做法是：

• 监听 track.onload 事件
• 或检查 track.readyState === TextTrack.LOADED（即值为 2）后再进行操作
• 动态添加 后，video.textTracks 列表会自动更新，但必须等到 load 事件触发后才可用

不要依赖 video.subtitleEnabled，这个属性根本不存在。

移动端字幕控件基本不可靠

iOS Safari 默认隐藏原生字幕按钮，且完全不响应 default 属性；旧版 Android WebView（尤其是 7.0 以下版本）甚至不触发 textTracks 列表。因此：

• 不要指望用户能点击控制条里的字幕开关
• 推荐自行实现 UI 开关，通过 JS 控制 track.mode
• 检测到 video.textTracks.length === 0 后，使用

  或 模拟字幕层作为 fallback

移动端兼容性是真实存在的断层问题，并非配置不当所致。