WebVTT字幕失效的三大主因：文件首行必须严格为顶格大写“WEBVTT”且无BOM；track元素须为video直接子元素并紧接source之后；服务端必须返回text/vtt MIME类型，三者缺一不可。
WebVTT 文件首行不是 WEBVTT 就直接失效
浏览器对 WebVTT 的解析极其严格，首行必须是顶格、全大写、无空格、无 BOM 的 WEBVTT，多一个空格、少一个字母、带 UTF-8 BOM 都会导致整条轨道被静默丢弃——Network 面板里可能看到 200 响应，但 track.readyState 永远卡在 0 或 1，::cue 样式也不生效。
检查办法：
- 用 VS Code 打开 .vtt 文件，右下角确认编码显示为
UTF-8（不是UTF-8 with BOM） - 按
Ctrl+Shift+P→ 输入 “Reopen with Encoding” → 选UTF-8强制重载 - 光标移到第一行最开头，按
→确认没有不可见字符（如ZERO WIDTH NO-BREAK SPACE） - 删掉所有注释行、
X-TIMESTAMP-MAP行前必须空一行，否则也判为非法
track 元素位置错一位，浏览器就当它不存在
track 必须是 video 的**直接子元素**，且必须紧接在所有 source 标签之后、 之前。放错位置不会报错，但 video.textTracks 列表为空，右键菜单里字幕项消失，连 fallback 都没机会触发。
常见错误结构：
立即学习“前端免费学习笔记（深入）”；
-
<video><track></track></video><source></source>（track在source前） -
<video><source></source><div><track></track></div></video>（包在div里） -
<video><source></source><!-- 注释 --><track></track></video>（中间有注释） -
<video><source></source></video><track></track>（track在video外）
正确顺序只有一种：<video><source></source><track></track></video>
生成可在 deepbi 沙箱 iframe 内运行或作为独立文件运行的交互式 HTML 页面，使用 `window.deepbi` JS SDK 实现数据查询、空间管理、文件浏览及用户操作。当用户提出以下需求时启用该能力： - 创建 KPI 仪表盘、数据表格、文件浏览器、成员列表、管理页面； - 明确要求“转成 dhtml”、“转译成 HTML”、“把 XX 页面转成……”、“控制台页面”、“管理后台”、“DeepBI 页面迁移”； - 提及位于 `apps/console/src/featur
服务端没返回 text/vtt MIME 类型，Chrome/Firefox 直接忽略
即使文件路径对、内容对、位置对，如果服务器返回的 Content-Type 不是 text/vtt，浏览器会把它当普通文本加载，不走 WebVTT 解析流程——track.readyState 不会变成 2，track.mode = "showing" 无效，控制台也不会报错。
验证与修复方式：
- 打开 DevTools → Network → 播放视频，找到 .vtt 请求 → 查看 Response Headers 中的
Content-Type - Nginx 配置需加：
types { text/vtt vtt; }，并确保include mime.types;已启用 - Apache 需在
.htaccess或配置中添加：AddType text/vtt .vtt - 本地开发用
python3 -m http.server默认不支持 .vtt 类型，必须改用serve或自定义服务
track 缺关键属性，字幕菜单里根本不出项
浏览器生成右键字幕菜单，依赖 kind、srclang、label 三个属性同时存在且合法。漏一个，对应轨道就不会出现在 UI 中——不是“不显示”，而是菜单里压根找不到那个语言选项。
必须逐项核对：
-
kind="subtitles"：必须全小写、拼写完整，"subtitle"、"captions "（末尾空格）、"subtitles"（引号内含不可见字符）都不行 -
srclang="zh"：必须是 BCP 47 标准码，"zh-CN"可以，"chinese"、"zh_CN"、空字符串均被忽略 -
label="中文(简体)"：不能为空，否则可能显示(no label)，多语种场景下无法区分 -
default属性只能出现在一个track上，多个会导致行为未定义
移动端尤其敏感：iOS Safari 会根据 srclang 和系统语言自动禁用不匹配轨道，哪怕 HTML 写对了，用户也看不到开关。
