track元素的src必须是绝对或相对URL,不能用file://路径或Blob URL,因浏览器会静默忽略;VTT文件需UTF-8无BOM、首行为WEBVTT、时间戳毫秒三位、服务端返回text/vtt MIME类型。

track 元素的 src 必须是绝对或相对 URL,不能是本地文件路径
浏览器加载字幕时会发起独立的 HTTP 请求,所以 src 值必须能被服务器解析为可访问资源。写成 file:///... 或直接拖进浏览器打开 HTML 文件(file:// 协议)时,track 几乎必然失败——跨域限制和 CORS 会拦截请求。
常见错误现象:Failed to load resource: net::ERR_FILE_NOT_FOUND 或控制台提示 Cross-Origin Request Blocked。
- 正确写法示例:
<track kind="subtitles" src="subtitles/en.vtt" srclang="en" label="English"> - 如果视频和字幕在同一目录,用相对路径即可;若部署在子目录(如
/video/),确保src路径相对于当前 HTML 文件位置 - 开发阶段别用双击打开 HTML 文件测试,启动一个本地服务(如 Python 的
python -m http.server或 VS Code Live Server)
.vtt 是唯一被广泛支持的字幕格式,别用 .srt 直接塞进 src
track 元素只原生支持 WebVTT(.vtt),即使内容和 .srt 相同,也必须转成合法 VTT 格式,否则浏览器静默忽略、不报错也不显示。
典型 VTT 文件开头必须有 WEBVTT 声明行,且时间戳格式为 hh:mm:ss.mmm(毫秒三位),不是 SRT 的逗号分隔。
立即学习“前端免费学习笔记(深入)”;
- 错误示例(SRT 风格,会被忽略):
1\n00:00:01,000 --> 00:00:04,000\nHello - 正确 VTT 示例:
WEBVTT 00:00:01.000 --> 00:00:04.000 Hello
- 转换工具推荐:在线搜
srt to vtt converter,或用命令行工具ffmpeg -i input.srt output.vtt
srclang 和 kind 必须匹配实际内容,否则字幕菜单不显示
浏览器字幕开关(如右键“字幕”菜单)依赖 srclang 和 kind 的组合。如果 srclang="zh" 但字幕里全是英文,或者 kind="captions" 却写了描述性文字(非对话),体验会异常。
-
kind="subtitles":翻译对白(最常用);kind="captions":含音效/说话人提示(适合听障);kind="descriptions":画面描述(需 screen reader 支持) -
srclang必须是有效 BCP 47 语言标签,比如zh、zh-CN、en-US,别写chinese或english - 多个
track时,确保label唯一且有意义,否则下拉菜单里全显示 “English” 无法区分
Chrome/Firefox 对 default 属性的支持很脆弱
加了 default 并不保证字幕自动开启——它只表示“用户未手动选择时的默认候选”,实际是否启用还取决于浏览器策略、用户历史设置、甚至页面是否在后台加载。
- 不要依赖
default实现强默认行为;需要强制显示,得用 JS 控制:video.textTracks[0].mode = 'showing' -
textTracks是动态集合,track元素插入后需等load事件或使用video.addEventListener('loadedmetadata', ...)再操作 - 移动端 Safari 对
default支持更差,基本无效,务必 JS 补位
text/vtt,否则 Chrome 可能拒绝加载。这两点不报明显错误,但字幕就是不出现——查 Network 面板看响应头和内容是否正常,比猜更省时间。



















