track元素需严格遵循嵌套位置、属性值、VTT格式、MIME类型及JS控制规范,任一环节出错均静默失效:必须位于后前;kind/srclang/label/src四属性缺一不可且值精确;VTT首行WEBVTT顶格无BOM、第二行空、时间戳毫秒三位、UTF-8无BOM、Content-Type为text/vtt;切换字幕须设track.mode="showing";file://协议下需本地服务避免CORS。

track 元素不是“加了就能出字幕”,浏览器会静默忽略绝大多数配置错误——连控制台都不报错,菜单里直接空着。
video 里 track 的位置和嵌套结构必须严格固定
浏览器只在 <video></video> 开始标签之后、所有 <source></source> 闭合之后、 之前这个狭窄区间内解析 track。
- track 写在 <source></source> 前面 → 被跳过
- track 包在 <div> 或其他容器里 → 不发起请求,<code>video.textTracks.length 恒为 0
- track 动态用 JS 插入已渲染的 video → 完全无效(必须随 HTML 一起加载)
- 多个 track 之间插了注释或空行 → 部分浏览器(如 Safari)中断后续解析
正确结构示例:
<video controls> <source src="movie.mp4" type="video/mp4"> <track kind="subtitles" src="zh.vtt" srclang="zh" label="中文(简体)" default> <track kind="subtitles" src="en.vtt" srclang="en" label="English"> </video>
track 四个属性一个都不能少,且值必须精确
浏览器不推断、不容错,缺任一或写错格式,该轨道就不出现在字幕菜单里:
- kind="subtitles":必须是这个字符串,不能是 "subtitle"、"captions"、"subtitles "(末尾空格也不行)
- srclang:必须是标准 BCP 47 码,如 "zh"、"zh-Hans"、"en-US";"chinese"、"cn"、"zh-cn" 全部无效
- label:用户在右键菜单或控件栏看到的名字,为空时显示 "(no label)",无法区分语种
- src:必须是相对或绝对 URL,不支持 Blob URL(如 blob:http://...),否则静默失败
WebVTT 文件本身必须通过四重校验
哪怕 HTML 和属性全对,VTT 文件错一个字符,整条轨道就失效: - 首行必须是顶格、全大写、无空格、无 BOM 的WEBVTT(webvtt、WebVTT、 WEBVTT 全挂)
- 第二行必须为空行(不能有空格或制表符)
- 时间戳格式严格为 00:00:01.234 --> 00:00:04.567:毫秒必须三位,箭头前后各一个空格
- 文件编码必须是 UTF-8 无 BOM(Windows 记事本默认带 BOM,务必用 VS Code 或 Notepad++ 选 “UTF-8 without BOM” 保存)
- 服务端返回 Content-Type: text/vtt(Nginx/Apache 需显式配置 MIME 类型),否则 Chrome/Firefox 拒绝解析
JS 控制字幕切换必须操作 mode,不是改 src 或 hidden
用户点击语言按钮后,不能靠修改 track.src 或设 track.hidden = false 来切换:
- 正确方式是遍历 video.textTracks,把目标轨道设为 track.mode = "showing",其余设为 "disabled"
- 切换前建议检查 track.readyState === 2(LOADED),避免未加载完成就启用
- 不要设多个 mode = "showing",否则渲染错乱
- default 属性只影响首次加载,用户手动切换后即以用户选择为准,刷新不重置
最常被忽略的一点:本地开发用 file:// 协议时,所有 .vtt 请求都会因 CORS 被拒——必须起本地服务(如 python3 -m http.server)才能验证真实行为。



















