字幕不显示90%是标签位置或格式错误：必须紧接后、为直接子元素；webvtt首行须为webvtt，utf-8无bom编码，时间戳格式正确，服务器返回text/vtt mime类型，且srclang、label、kind属性缺一不可。

字幕不显示，90% 是 <track></track> 标签位置、格式或属性写错了——不是浏览器不支持，而是它根本没认出这是条有效轨道。

video 里 <track></track> 必须紧接 <source></source> 后且是直接子元素

浏览器只在 <video></video> 开始标签之后、结束标签之前，并且紧接在所有 <source></source> 之后的位置识别 <track></track>。放错位置等于没写。

• <track></track> 不能包在 <div> 或其他容器里 <li>不能写在 <code><source></source> 前面（常见错误）
• 不能写在 外面，哪怕只多一个换行
• 多个 <track></track> 之间不能有空标签或注释干扰解析

WebVTT 文件必须满足四个硬性条件

哪怕只漏一个，Chrome/Firefox 都会静默失败：不报错、不加载、字幕空白。


Html2md
使用 Readability + Turndown 将 HTML 页面转换为干净的、Agent 友好的 Markdown。去除导航栏、广告、页脚、Cookie 横幅、社交按钮等干扰元素。支持 URL...
下载
• 首行必须是 WEBVTT（全大写，无空格，无 BOM）
• 编码必须是 UTF-8 无 BOM（用 VS Code 打开 → 右下角点编码 → “Save with Encoding” → 选 UTF-8）
• 时间戳格式必须为 00:00:01.234 --> 00:00:04.567，不能用 SRT 的序号行或空行分隔
• 服务器需返回 Content-Type: text/vtt，否则部分浏览器拒绝加载（Nginx/Apache 要手动配 MIME 类型）

srclang、label、kind 缺一不可

kind 必须是 "subtitles"、"captions" 或 "descriptions" 之一，写成 "subtitle" 或空值会被忽略。

• srclang 不只是“可选语言标识”，它是 JS 切换时定位轨道的唯一依据；推荐用标准 BCP 47 码，如 "zh"、"en-US"，别用 "ch" 或 "cn"
• label 不只是 UI 文字，缺失会导致浏览器下拉菜单里只显示“字幕”两个字，用户无法区分中英文
• 多个 <track></track> 中只能有一个带 default 属性，否则全部失效

JS 控制字幕前必须等

track.readyState === 2

直接设 track.mode = "showing" 很可能无效——因为文件还没加载完。浏览器不会等你，它只会跳过。

• 监听 video.textTracks[i].onload 或检查 track.readyState === 2（即 TextTrack.LOADED）再操作
• 禁用当前轨道时，记得把其他同 kind 的轨道设为 "disabled"，否则可能多轨同时显示
• 移动端 Safari 默认隐藏原生字幕按钮，且不响应 default，必须自己做 UI + JS 控制 mode

最容易被忽略的是：本地开发时用 file:// 协议打开 HTML，所有 .vtt 加载都会失败——必须起本地服务（如 python3 -m http.server）；还有就是服务器没配 text/vtt MIME 类型，Safari 就直接拒收，连控制台都不报错。