字幕不显示的主因是track标签位置错误、WebVTT格式或编码不合法、track属性缺失/拼写错误、video未加载完成就调用addTextTrack。需确保track紧接source后且为video直接子元素,WebVTT首行为纯WEBVTT、UTF-8无BOM、时间戳格式正确、服务器返回text/vtt,track属性srclang、label、kind、src齐全且正确,JS动态添加须等loadedmetadata事件并设mode="showing"。

track标签位置错:必须紧接后且是
浏览器只在<video></video>开始标签之后、结束标签之前,并且**紧接在所有<source></source>之后**的位置识别<track></track>。放错位置等于没写。
-
<track></track>不能包在<div>或其他容器里 <li>不能写在<code><source></source>前面(常见错误) - 不能写在
外面,哪怕只多一个换行 - 验证方法:打开开发者工具 → Elements 面板,确认
<track></track>是<video></video>的直接子节点,且排在所有<source></source>之后 - 首行必须是纯文本
WEBVTT(不能有空格、BOM、注释) - 文件必须保存为 UTF-8 无 BOM 编码(VS Code 右下角可查/切换)
- 时间戳格式必须严格为
HH:MM:SS.mmm --> HH:MM:SS.mmm,毫秒位固定三位 - 服务器必须返回
Content-Type: text/vtt;本地双击打开时若用 file:// 协议,部分浏览器会拒绝加载,需起本地服务测试 -
kind="subtitles"(不是 subtitle 或 captions) -
srclang="zh"必须与实际语言匹配,否则 Safari 可能忽略 -
label="中文"任意非空字符串即可,但不能为空或仅空格 -
src路径要能被浏览器正确请求到(Network 面板看是否 404) - 不要在
DOMContentLoaded就调用,而应监听loadedmetadata事件 - 动态添加时,
addTextTrack()返回的TextTrack对象需手动设mode = "showing" - 更稳妥的做法仍是用 HTML 原生
<track></track>,避免 JS 时机问题
WebVTT文件格式或编码不合法
字幕不显示,90% 是因为浏览器压根没认出这是条有效轨道——不是不支持,而是解析失败。
track属性缺失或拼写错误
<track></track>的四个属性中,srclang、label、kind 和 src 缺一不可,且大小写敏感。
htmlq 是一个命令行工具,使用 CSS 选择器从 HTML 中提取内容,相当于 jq 的 HTML 版本。该工具使用 Rust 编写,允许你通过 CSS 选择器将 HTML 管道化,直接从终端提取文本、属性和结构化内容。
video未加载完成就调用addTextTrack
如果用 JS 动态添加字幕轨道(比如video.addTextTrack()),必须等video.readyState >= 1,否则返回 null 或静默失败。
立即学习“前端免费学习笔记(深入)”;
最容易被忽略的是:即使所有代码都对,只要 WebVTT 文件开头多了个 UTF-8 BOM 字节,或者服务器没配对text/vtt MIME 类型,字幕就彻底不会出现——它不会报错,只是安静地消失。


















