HTML视频添加字幕方法\_WebVTT格式详解

想让HTML视频字幕稳定显示？关键不在简单加个``标签，而在于严守WebVTT规范的四大硬性条件：首行必须是无空格无BOM的全大写`WEBVTT`、文件编码必须为UTF-8无BOM、时间戳格式须严格匹配`00:00:01.234 --> 00:00:04.567`（毫秒三位+双空格）、服务器必须返回`Content-Type: text/vtt`；同时``必须作为`

track 标签本身不“添加字幕”，它只是向 video 元素声明一条外部字幕轨道；能否显示，取决于 WebVTT 文件是否合规、路径是否可访问、浏览器是否加载成功，以及用户是否手动启用。

WebVTT 文件必须满足四个硬性条件

Chrome、Firefox、Edge 会静默失败——控制台可能无报错，但字幕就是不出现。漏掉任意一条，track 就等于没写。

• 首行必须是 WEBVTT（全大写、独占一行、前后无空格、无 BOM）
• 编码必须是 UTF-8 无 BOM（VS Code 保存时选 “UTF-8”，别选 “UTF-8 with BOM”）
• 时间戳格式严格为 00:00:01.234 --> 00:00:04.567（毫秒必须三位，箭头前后各两个空格）
• 服务器需返回 Content-Type: text/vtt（Nginx/Apache 需手动配置 MIME 类型，否则 Safari 可能拒绝加载）

track 标签位置和属性不能省略或写错

浏览器只在 video 开始标签之后、所有 source 闭合之后、video 结束标签之前识别 track。放错位置，等于没加。

• 必须是 video 的**直接子元素**，不能包在 div 或注释里
• kind="subtitles" 不可省略或拼错（"subtitle" 或空值会被忽略）
• srclang 必须是合法 BCP 47 码（如 "zh"、"en-US"，不能写 "ch" 或 "english"）
• label 建议填写（否则播放器下拉菜单里只显示“字幕”，用户无法区分语言）
• default 属性最多只能在一个 track 上使用，多个会导致全部失效

JavaScript 控制字幕开关必须等 readyState === 2

直接设 track.mode = "showing" 很可能无效——因为字幕文件还没加载完。浏览器不会等你，它只会跳过。

• 先监听 track.onload，或检查 track.readyState === TextTrack.LOADED（即值为 2）再操作
• 一次只能有一个 subtitles 轨道设为 "showing"，其余同 kind 的必须设为 "disabled"，否则 Safari/Edge 行为不一致
• 禁用不要用 track.hidden = false，这个 DOM 属性不影响字幕渲染逻辑
• 移动端 iOS Safari 默认不触发 textTracks 列表（video.textTracks.length 可能恒为 0），得 fallback 到 div 渲染

为什么 SRT 文件经常不工作

浏览器对 track 加载的 SRT 支持极不稳定：Firefox 原生解析，Chrome 实际是内部转成 WebVTT 再处理，稍有格式偏差就失败。

• SRT 时间戳用逗号分隔毫秒（00:01:23,456），但 Chrome 要求句点（00:01:23.456）
• SRT 的序号行、空行分隔方式不符合 WebVTT 规范，Chrome 可能静默跳过
• 哪怕内容一样，SRT 改后缀成 .vtt 也不行——必须真正转换格式，补上 WEBVTT 首行
• 稳妥做法：用 vtt-tools 或在线转换器转 SRT → WebVTT，再配 src="xx.vtt"

最容易被忽略的是服务器 MIME 类型和 UTF-8 无 BOM —— 这两者出问题，连控制台都不会报错，字幕就彻底消失。真机测试时，iOS Safari 的 textTracks 行为和桌面完全不同，别只信开发工具里的模拟结果。

本篇关于《HTML视频添加字幕方法\_WebVTT格式详解》的介绍就到此结束啦，但是学无止境，想要了解学习更多关于文章的相关知识，请关注golang学习网公众号！