17370845950

HTML5视频字幕必须使用标签，且需满足：作为video直接子元素、位于source之后、kind="subtitles"、srclang为合法BCP 47码、src指向CORS允许的WebVTT文件（首行WEBVTT、无BOM、时间戳毫秒三位），iOS 14以下需降级方案。

video 标签里加字幕必须用 ，不能靠 JS 手动插入 DOM

HTML5 字幕不是靠 document.createElement('div') 动态塞进视频里的，浏览器只认 标签。它必须是 的直接子元素，且位置要在所有 之后、 闭合前。否则 Chrome / Safari 会直接忽略，控制台也不报错——字幕就是不显示。

• 必须有 kind="subtitles"（不是 "caption"，除非你真在做聋人无障碍字幕）
• srclang 必须是合法 BCP 47 语言码，比如 zh、zh-CN、en，写 chinese 或空值会导致字幕不可选
• label 是用户在右键菜单里看到的名字，建议写清楚，比如 label="简体中文"
• 浏览器默认不自动启用字幕，得靠用户手动点「字幕」按钮或用 JS 调 video.textTracks[0].mode = "showing"

的 src 必须是 WebVTT 文件，且 HTTP 响应头要支持 CORS

哪怕文件就在同域下，Chrome 和 Edge 对 也会发预检请求。如果服务器没返回 Access-Control-Allow-Origin: *（或对应域名），控制台会报 Failed to load resource: net::ERR_FAILED，字幕静默失败。

• 本地双击 HTML 文件（file:// 协议）时，所有 都会被禁用，这是浏览器安全限制，必须起本地服务（如 python3 -m http.server）测试
• VTT 文件首行必须是 WEBVTT，不能有 BOM，不能是 UTF-8 with BOM 编码，否则 Firefox 显示为空白
• 时间戳格式必须严格：00:00:01.234 --> 00:00:03.456，毫秒位必须是三位，写成 .23 或 .2345 都会解析失败

JS 控制字幕开关要用 textTracks，不是 tracks

别被 IDE 自动补全骗了：video.tracks 是只读的类数组，真正可操作的是 video.textTracks。它的每个项是 TextTrack 实例，mode 属性决定是否显示：

const video = document.querySelector('video');
const track = video.textTracks[0];
track.mode = 'disabled'; // 关闭
track.mode = 'hidden';   // 隐藏但保持解析（可用于搜索）
track.mode = 'showing';  // 显示（等效于用户手动开启）

• textTracks 是实时集合，动态添加 后会立即反映，但 mode 默认是 'disabled'
• 监听字幕切换要用 video.textTracks.onchange，不是 video.addEventListener('trackchange')（后者不存在）
• 多个字幕轨道共存时，只有 mode === 'showing' 的那个生效，其他自动为 'disabled'

移动端 Safari 字幕支持弱，iOS 15+ 才支持 textTracks API

iOS 14 及更早版本中， 虽能渲染，但 video.textTracks 是空数组，mode 无法设置，也无法监听变更。用户只能依赖系统控制条里的字幕开关，且该开关在某些机型上默认隐藏。

立即学习“前端免费学习笔记（深入）”；

• 检测兼容性不要只查 'textTracks' in HTMLMediaElement.prototype，还得实际创建 并检查 video.textTracks.length
• 若需 iOS 14 兼容，得降级方案：用 + timeupdate 事件手动同步字幕，但会丢失原生定位、字体缩放、无障碍支持
• WebVTT 的 、 等 HTML 标签在 Safari 上被忽略，只支持 （class）和 （underline）等有限标记
实际用的时候，最常卡在 VTT 文件编码、CORS、以及 iOS 版本兼容这三处。尤其开发阶段在本地双击打开，90% 的“字幕不显示”问题都源于此。