WebVTT字幕需同源加载、时间戳格式严格、实时字幕须用VTTCue动态注入,且iOS需CSS降级;否则将静默失败或渲染异常。

WebVTT 文件必须放在同源路径下才能被 <track></track> 加载
浏览器对 <track></track> 的 src 属性执行严格同源策略,即使服务器返回了正确的 CORS 头,多数浏览器(Chrome、Firefox)仍会拒绝加载跨域字幕文件。常见现象是视频正常播放,但字幕完全不显示,控制台却无报错——这是最典型的“静默失败”。
实操建议:
生成可在 deepbi 沙箱 iframe 内运行或作为独立文件运行的交互式 HTML 页面,使用 `window.deepbi` JS SDK 实现数据查询、空间管理、文件浏览及用户操作。当用户提出以下需求时启用该能力: - 创建 KPI 仪表盘、数据表格、文件浏览器、成员列表、管理页面; - 明确要求“转成 dhtml”、“转译成 HTML”、“把 XX 页面转成……”、“控制台页面”、“管理后台”、“DeepBI 页面迁移”; - 提及位于 `apps/console/src/featur
- 把
subtitles.vtt放在和 HTML 同目录,或同域名下的静态资源路径(如/assets/subtitles.vtt) - 用相对路径写
src,避免协议/域名硬编码:<track kind="subtitles" src="subtitles.vtt" srclang="zh" label="中文"></track> - 检查响应头是否含
Content-Type: text/vtt;Nginx 需显式添加:types { text/vtt vtt; }
WebVTT 时间戳格式错误会导致整条轨道失效
哪怕只有一行时间戳多了一个空格、少了一个小数点,整个 .vtt 文件都会被浏览器丢弃,且不会提示具体哪一行出错。常见错误包括:00:01:23.45 写成 00:01:23.450(毫秒位超三位)、使用逗号代替英文句点、时间范围起始大于结束。
正确格式示例(注意空行、句点、空格):
立即学习“前端免费学习笔记(深入)”;
WEBVTT 00:00:01.200 --> 00:00:04.500 欢迎观看实时字幕演示 00:00:04.600 --> 00:00:07.800 字幕需逐帧对齐音画
实操建议:
- 用 VS Code 安装
WebVTT Syntax插件,实时高亮语法错误 - 避免手写时间戳,用
ffmpeg导出带时间轴的 SRT 再转 VTT(ffmpeg -i in.srt out.vtt) - 加载后调用
video.textTracks[0].mode = 'showing'强制启用,便于快速验证是否加载成功
实时字幕不能靠 <track></track> 自动更新,必须用 TextTrackCue 动态注入
<track></track> 只支持静态字幕文件,无法响应流式更新。所谓“实时”,本质是 JS 在运行时动态创建并插入 VTTCue(或兼容的 TextTrackCue)对象到 textTrack.cues 列表中。
关键步骤:
- 先用
video.addTextTrack('subtitles', '', 'zh')创建空轨道 - 获取轨道引用:
const track = video.textTracks[0] - 每收到一条新字幕数据,构造 cue:
const cue = new VTTCue(startTime, endTime, text) - 调用
track.addCue(cue)—— 注意:cue 一旦添加,就不能修改时间轴,只能移除重加
性能提醒:频繁 addCue 可能触发重排,建议单次最多添加 3–5 条,旧 cue 超过 10 秒未显示就用 track.removeCue(oldCue) 清理。
移动端 Safari 对 VTTCue 的 line 和 align 属性支持极差
想让字幕固定在屏幕底部中央?别依赖 cue.line = -2 或 cue.align = 'center'。iOS 16+ 之前几乎全部忽略这些属性,字幕默认顶对齐、左对齐,且字体大小不可控。
绕过方案:
- 放弃原生样式控制,用 CSS 覆盖
::cue伪元素(仅限基础样式):video::cue { color: white; font-size: 1.2em; text-shadow: 0 0 2px #000; } - 如需精确定位,改用绝对定位的
<div> 层叠在 <code><video></video>上,JS 同步更新内容与显隐状态 - 检测环境:
if (!('VTTCue' in window))降级为 div 方案,尤其针对 iOS 15 及更早版本
实时字幕最难的不是解析文本,而是 cue 生命周期管理与跨端渲染一致性——时间精度、内存清理、样式 fallback 这三块,漏掉任一环节,用户看到的就是跳闪、堆叠或空白。


















