track元素需严格满足结构、属性、VTT文件及服务端四重条件:必须紧贴source后作为video直接子元素;kind、srclang、label、src缺一不可;VTT首行为WEBVTT、UTF-8无BOM、时间戳格式正确、服务端返回text/vtt;default仅单设且加载成功才生效。

track 元素不会自动生效,哪怕标签写对了,只要结构、属性、文件格式或服务端响应中任意一环出错,浏览器就静默忽略——连控制台警告都不会有。
track 必须紧贴 source 之后且是 video 的直接子元素
浏览器只在 开始标签后、所有 闭合后这个极窄区间内解析 。放错位置等于没写。
-
写在前面 → 被完全跳过 -
包在里或放在外 →video.textTracks.length恒为0,Network 面板里看不到请求- 多个
之间插了 HTML 注释()或空行 → Safari 可能中断后续轨道解析- 用 JavaScript 动态
appendChild插入 → 失效(已加载完成,不会再重新扫描 DOM)kind、srclang、label、src 四个属性一个都不能少
浏览器不做任何容错推断。漏任一属性,该轨道就不会出现在右键字幕菜单中,也不会被
video.textTracks收录。-
kind="subtitles":必须全小写、不能多空格、不能写成caption或subtitles(末尾带空格) -
srclang:必须是合法 BCP 47 语言码,如zh-Hans、en-US、ja;ch、cn、chinese全部无效 -
label:用户在字幕开关菜单里看到的名称,为空时可能显示(no label),无法区分语种 -
src:必须指向可访问的 .vtt 文件路径,相对路径需以当前 HTML 所在目录为基准
VTT 文件必须满足四条硬性条件
哪怕
标签完全正确,VTT 文件本身不合规,字幕照样不出现。- 首行必须严格为
WEBVTT(全大写、无空格、无 BOM) - 编码必须是 UTF-8 无 BOM(VS Code 右下角选 “Save with Encoding” → UTF-8)
- 时间戳格式必须为
00:00:01.234 --> 00:00:04.567(毫秒三位、箭头前后各一个空格) - 服务端必须返回
Content-Type: text/vtt(Nginx/Apache 需显式配置 MIME 类型;本地file://协议下必挂,必须走 HTTP 服务)
default 属性只能设在一个 track 上,且有前提
default表示页面加载时默认启用该轨道,但它不是“设了就生效”。- 只能在一个
上设default,多个会互相抵消 - 用户手动切换过字幕后,
default就不再起作用(浏览器记住用户偏好) - 如果该
因路径错误、MIME 不对或 VTT 格式非法而加载失败,default会静默失效,不会 fallback 到其他轨道 - 移动端部分浏览器(如 iOS Safari)会忽略
default,始终以系统语言匹配优先
最常被忽略的是服务端 MIME 类型和本地
file://协议限制——这两点导致大量开发阶段“明明代码一模一样却不出字幕”的问题。别急着改 HTML,先开 Network 面板看.vtt请求是否返回 200 和text/vtt。 - 多个
前端入门到VUE实战笔记:立即使用
在学习笔记中,你将探索 前端 的入门与实战技巧!











