如何将HTML视频字幕track标签与vtt文件有效结合使用？

本文共计999个文字，预计阅读时间需要4分钟。

浏览器只认可 标签。

正确结构示例：

<video controls> <source src="movie.mp4" type="video/mp4"> <track kind="subtitles" label="中文" srclang="zh" src="subtitles.zh.vtt" default> </video>

• kind="subtitles" 是最常用值；用 captions 时会强制显示（含音效描述），descriptions 则需辅助技术支持
• srclang 必须是合法 BCP 47 语言标签（如 zh、zh-Hans、en-US），错写成 ch 或 cn 会导致字幕不自动匹配
• default 属性只允许一个 track 使用，否则行为未定义；用户手动切换后该属性不再生效

vtt 文件路径 404 是最常见的失败原因

浏览器对 <track src="..."> 的请求走的是普通 HTTP 请求，和 CSS/JS 一样受同源策略限制，也一样会因路径错误返回 404。开发者常误以为“文件放同一目录就行”，但实际路径是相对于当前 HTML 页面 URL 的。

• 如果 HTML 地址是 https://example.com/pages/video.html，而 vtt 在 /assets/subs/en.vtt，那 src 得写成 "/assets/subs/en.vtt"（绝对路径）或 "../assets/subs/en.vtt"（相对路径）
• 开发时用 VS Code Live Server 或 Python http.server 能避免 file:// 协议下跨域读取失败；直接双击打开 HTML 会导致 vtt 加载被拒
• vtt 文件响应头必须包含 Content-Type: text/vtt，Nginx/Apache 需单独配置；否则 Chrome 会静默忽略（无报错，但字幕不出现）

vtt 文件格式稍有瑕疵就会完全失效

WebVTT 不是“差不多能看就行”的格式，浏览器解析极其严格：BOM 头、空行、时间戳格式、非法字符，任一出错都会让整段字幕丢弃，且控制台通常只报 “Failed to parse WebVTT” 这类模糊提示。

立即学习“前端免费学习笔记（深入）”；

• 必须以 WEBVTT 开头（全大写，顶格，前后无空格），后面紧跟一个空行
• 时间戳格式为 HH:MM:SS.mmm --> HH:MM:SS.mmm，毫秒必须三位（001，不能 1 或 01）
• 禁止使用 UTF-8 BOM；推荐用 VS Code 保存为 “UTF-8”（不是 “UTF-8 with BOM”）
• 避免在文本中使用 Windows 换行符 \r\n 混搭；统一用 \n 更稳妥

JavaScript 动态添加 track 容易漏掉 load() 调用

用 JS 创建 <track> 后插入到 <video>，不代表字幕会立刻可用。浏览器不会自动触发加载，必须显式调用 video.load() 或触发一次 video.src 变更（哪怕设成当前值）。

• 错误写法：video.appendChild(track) → 字幕不出现
• 正确写法：video.appendChild(track); video.load();
• 如果视频已播放中，还需调用 track.track.mode = "showing" 才能立即显示（默认是 disabled）
• 动态添加多个 track 时，video.textTracks 是实时更新的，但新 track 的 readyState 初始为 0（not loaded），需监听 load 事件确认加载完成

vtt 的容错性比想象中低，哪怕只是多了一个空格或换行，整个文件就可能被跳过。调试时优先打开 Network 面板看 vtt 是否 200，再检查 Response 内容是否符合 WebVTT 规范，最后才查 JS 逻辑。