video标签内track必须位于source之后且在video内部,需设kind="subtitles"、srclang、label;动态切换须用textTracks API设mode,不可改src;WebVTT格式须严格:顶格大写WEBVTT、空行、标准时间戳、无BOM、纯ASCII标点。

video 标签内
浏览器只在 video 元素首次加载时解析 track 的 src,后续用 JS 修改 track.src 完全无效——不会报错,但字幕不会更新。动态字幕不是“换一个 src”,而是提前把所有语言的 track 都写进 HTML,再用 JS 控制 mode。
正确结构顺序必须是:video → source(可多个)→ track(可多个)→ 。把 track 放在 source 前面、或写在 video 外面,字幕轨道根本不会被识别。
- 每个
track必须带kind="subtitles"、srclang(如zh-Hans)、label(如"中文(简体)"),缺一不可 -
default只能加在一个track上,作为初始启用项;其余语言靠 JS 切换 - 本地开发时若用
file://协议,.vtt会因 CORS 被拒,务必起服务(如python3 -m http.server)
WebVTT 文件格式错一个字符,整条字幕就静默失效
WebVTT 解析器零容错:WEBVTT 必须顶格、全大写、无空格、无 BOM;首行后必须空一行;时间戳严格为 00:00:01.234 --> 00:00:03.456(毫秒三位、箭头前后各两个空格)。
常见静默失败点:
立即学习“前端免费学习笔记(深入)”;
生成可在 deepbi 沙箱 iframe 内运行或作为独立文件运行的交互式 HTML 页面,使用 `window.deepbi` JS SDK 实现数据查询、空间管理、文件浏览及用户操作。当用户提出以下需求时启用该能力: - 创建 KPI 仪表盘、数据表格、文件浏览器、成员列表、管理页面; - 明确要求“转成 dhtml”、“转译成 HTML”、“把 XX 页面转成……”、“控制台页面”、“管理后台”、“DeepBI 页面迁移”; - 提及位于 `apps/console/src/featur
- 用记事本保存为 UTF-8 → 自动带 BOM → Firefox 显示空白,Chrome 直接跳过
- 时间写成
00:01:02.5 --> 00:01:04.8(毫秒少一位)→ 整个 cue 被忽略 - 写
webvtt或WEBVTT(末尾空格)→ 浏览器不认作合法 VTT - 中文内容里混入 Word 中的全角标点或智能引号 → 显示为方块或乱码
切换语言必须用 textTracks API 设置 mode,不能只靠 HTML
HTML 里写十个 track,用户不手动点播放器字幕菜单,其余语言永远是 disabled 状态。要实现 JS 控制切换,得操作 video.textTracks 列表:
function switchSubtitle(lang) {
const tracks = video.textTracks;
for (let i = 0; i < tracks.length; i++) {
if (tracks[i].srclang === lang) {
tracks[i].mode = "showing";
} else {
tracks[i].mode = "disabled";
}
}
}
注意:textTracks 是实时列表,但它的索引和 DOM 中 track 的顺序一致;mode 设为 "showing" 后,浏览器不会自动滚动到当前时间点字幕——如果需要精确同步,得监听 timeupdate 手动匹配 cue。
- Safari 对字幕菜单极其保守:没
kind="subtitles"+ 至少一个default,右键根本不出字幕选项 - Chrome 允许用户右键开启/关闭,Safari 默认隐藏该菜单,除非你显式满足上述条件
-
track.mode = "hidden"会隐藏字幕但保留轨道,"disabled"则彻底停用
不要用 Blob URL 给 track.src 赋值,浏览器会静默忽略
track.src 不支持 Blob URL(如 blob:http://localhost:8000/xxx),这是规范限制,不是兼容性问题。哪怕你用 URL.createObjectURL() 生成了合法 URL,浏览器也会直接跳过加载,控制台无任何提示。
动态生成字幕文本的唯一可行路径是:
- 用
fetch拿到原始 VTT 字符串 - 创建
new Blob([vttText], {type: "text/vtt"})→ 这步只是中间处理 - **不能**把 Blob URL 赋给
track.src;而是需先将内容写入临时track元素(DOM 中已存在),再设mode = "showing" - 更稳妥的做法:服务端预生成所有语言的 .vtt 文件,前端只做
mode切换
真正容易被忽略的是:VTT 文件的 MIME 类型必须是 text/vtt。Nginx/Apache 需显式配置,否则即使路径对、格式对,Safari 也会拒绝加载。


















