HTML视频字幕不显示，90%是src路径失效、kind类型不匹配或资源未加载，而非标签丢失；需检查srclang、default属性、MIME类型、VTT格式合法性及跨域问题。
HTML 视频字幕（<track></track>）丢失，90% 不是标签被删了，而是 src 路径失效、kind 类型不匹配，或浏览器根本没加载到该资源。
生成可在 deepbi 沙箱 iframe 内运行或作为独立文件运行的交互式 HTML 页面，使用 `window.deepbi` JS SDK 实现数据查询、空间管理、文件浏览及用户操作。当用户提出以下需求时启用该能力： - 创建 KPI 仪表盘、数据表格、文件浏览器、成员列表、管理页面； - 明确要求“转成 dhtml”、“转译成 HTML”、“把 XX 页面转成……”、“控制台页面”、“管理后台”、“DeepBI 页面迁移”； - 提及位于 `apps/console/src/featur
检查 <track></track> 标签是否真“丢失”还是“未激活”
先打开浏览器开发者工具（F12），切换到 Elements 面板，展开 <video></video> 元素。如果能看到 <track kind="subtitles" src="xxx.vtt"></track> 但字幕不显示，说明不是“丢失”，而是：
- srclang 缺失或与系统语言不匹配（Chrome 默认只启用 srclang 匹配当前页面语言或浏览器语言的 track）
- default 属性没加，且用户没手动在视频右键菜单里开启字幕
- kind 写成 "caption" 却传了纯翻译字幕（无说话人/音效描述），部分浏览器会静默忽略
- 字幕文件返回 HTTP 状态码不是 200（比如 404、403、CORS 阻止），控制台 Network 标签里搜 .vtt 就能确认
验证 src 路径是否真实可达
别只看 HTML 里写的路径，要模拟浏览器实际请求行为：
- 把 src 值（如 "./sub/en.vtt"）完整粘贴进浏览器地址栏，看能否直接下载或渲染文本内容
- 如果是相对路径，注意它相对于 当前 HTML 页面 URL，不是相对于 JS 文件或服务器根目录
- 开发时用本地 file:// 协议打开 HTML？那 <track></track> 的 src 会被浏览器跨域策略拦截——必须起一个本地服务（如 Python 的 python -m http.server 8000）再访问 http://localhost:8000/xxx.html
- Nginx/Apache 等服务器需确保 .vtt 被识别为 text/vtt MIME 类型，否则 Chrome 拒绝加载（查响应头 Content-Type）
确认字幕文件内容格式合法
即使路径通、MIME 对，.vtt 文件本身有硬性语法要求：
- 第一行必须是 WEBVTT（全大写，前后不能有空格或 BOM）
- 每个 cue 块之间至少一个空行
- 时间戳格式必须为 HH:MM:SS.mmm --> HH:MM:SS.mmm（毫秒三位，不能少）
- 不能含 HTML 标签（<b></b> 等会被忽略），仅支持有限的 <c></c>、<i></i>、<u></u>
- 用 VS Code 打开后右下角确认编码是 UTF-8（无 BOM），否则中文可能乱码导致解析失败
源文件关联失效的典型场景
所谓“源文件关联”，本质是 HTML、<video></video> 的 src、<track></track> 的 src 三者路径关系断裂：
- 视频文件从 /videos/demo.mp4 移到 /assets/media/demo.mp4，但忘记同步改 <track src="../sub/demo.vtt"></track>
- 构建工具（如 Webpack/Vite）把字幕文件 hash 后输出为 demo.abc123.vtt，但 HTML 中仍写死原始名
- 使用 CDN 时，HTML 部署在 https://a.example.com，但 <track src="https://b.example.com/sub.vtt"></track> 缺少 CORS 头（Access-Control-Allow-Origin: *）
- 后端模板引擎（如 Jinja2、Thymeleaf）生成 HTML 时，track.src 变量为空或拼接错误，最终渲染出 <track src=""></track>（浏览器静默跳过）
最易被忽略的一点：Chrome 和 Firefox 对 <track></track> 的加载时机敏感——如果 <video></video> 已开始播放，再动态插入 <track></track> 标签，部分版本不会自动启用。务必在 <video></video> 加载完成（loadedmetadata 事件后）再添加，或直接写死在 HTML 源码里。
