track元素仅声明外部WebVTT轨道,字幕显示需track属性、.vtt文件格式、HTML结构三者同时合规;缺一环则字幕菜单中完全不出现。

track 元素本身不“引入”字幕,它只是声明一个外部 WebVTT 轨道;真正让字幕显示出来的,是浏览器对 track 属性、.vtt 文件格式、HTML 结构三者同时合规的响应。漏掉任一环,字幕就彻底消失——不是错位,是菜单里压根没选项。
track 必须放在 video 内且紧贴 source 之后
浏览器只在 <video></video> 开始标签后、所有 <source></source> 闭合后、 前解析 track。放错位置等于没写,控制台零报错。
- ❌ 错误:写在
<source></source>前、嵌套在<div> 里、或出现在 <code>外 - ❌ 错误:用 JS 动态插入到已渲染的
<video></video>中(无效) - ✅ 正确顺序示例:
<video controls><br> <source src="lesson.mp4" type="video/mp4"><br> <track kind="subtitles" src="zh.vtt" srclang="zh" label="中文(简体)" default><br></video>
-
kind="subtitles":必须全小写、拼写完整;kind="subtitle"或kind="subtitles "(末尾空格)均失效 -
src:只能是相对路径(如./zh.vtt)或绝对 URL;Blob URL(如blob:http://...)会被静默忽略 -
srclang="zh":必须是标准 BCP 47 码,如zh、en-US、ja;chinese、zh_CN、空值都无效 -
label="中文(简体)":用户在菜单里看到的名字;为空时可能显示(no label),多语言场景下无法区分 - 首行必须是顶格、全大写、无空格、无 BOM 的
WEBVTT(webvtt或WebVTT都失败) - 时间戳格式强制为
00:00:01.234 --> 00:00:04.567:小时/分钟/秒两位,毫秒三位,箭头前后各两个空格 - 文件编码必须是 UTF-8 无 BOM:Windows 记事本默认带 BOM,务必用 VS Code 或 Notepad++ 选 “UTF-8 without BOM” 保存
- 服务端需返回
Content-Type: text/vtt;Nginx/Apache 要显式配置 MIME 类型,否则 Safari 可能拒绝解析 - Chrome/Firefox/Safari 均禁用
file://下的跨域请求,即使字幕和 HTML 在同一文件夹 - 解决方法:起本地服务,例如终端运行
python3 -m http.server,然后访问http://localhost:8000 - 若部署上线,确保
src路径同源,或服务端配置Access-Control-Allow-Origin: *
四个属性缺一不可:kind、src、srclang、label
浏览器靠这四个值生成右键字幕菜单项。少一个,对应轨道就不出现在 UI 里。
vtt 文件必须严格合规,容错率为零
哪怕一个字符错,整段字幕都会被跳过。常见雷区集中在开头、时间戳、编码三处。
生成可在 deepbi 沙箱 iframe 内运行或作为独立文件运行的交互式 HTML 页面,使用 `window.deepbi` JS SDK 实现数据查询、空间管理、文件浏览及用户操作。当用户提出以下需求时启用该能力: - 创建 KPI 仪表盘、数据表格、文件浏览器、成员列表、管理页面; - 明确要求“转成 dhtml”、“转译成 HTML”、“把 XX 页面转成……”、“控制台页面”、“管理后台”、“DeepBI 页面迁移”; - 提及位于 `apps/console/src/featur
本地开发时 vtt 加载失败的真正原因
用 file:// 协议直接双击打开 HTML,所有 .vtt 都会静默失败——这不是代码问题,是浏览器策略。
立即学习“前端免费学习笔记(深入)”;
controls、甚至是否设了 default 都无关——只取决于那四个属性有没有写对、.vtt 文件有没有被浏览器当作合法文本轨道加载成功。调试时先检查 Network 面板里 .vtt 请求是否 200,再看 Console 有无 MIME 类型警告,最后确认右键菜单里有没有对应 label。其他都是后续。


















