<track>元素默认不显示字幕,需用户手动开启或通过JS设置textTracks[i].mode = "showing";default属性仅表示可默认启用,不保证可见;VTT文件须正确加载且格式合规,否则静默失效。

track 元素默认不显示字幕
HTML 中的 <track> 标签本身不会自动显示字幕,即使它已正确加载并关联到 <video> 或 <audio> 元素。浏览器只在用户主动开启字幕(比如点击播放器的“CC”按钮)时才渲染字幕,这是规范强制要求的行为——default 属性只是声明“该轨道可被默认启用”,但是否真显示,还取决于浏览器策略和用户设置。
-
default属性仅影响轨道的“启用状态”,不等于“视觉可见”。即使写了<track kind="subtitles" srclang="zh" label="中文" default>,字幕仍可能不显示 - Chrome、Firefox、Safari 都会忽略
default并默认隐藏字幕,除非用户手动打开字幕开关(或通过 JS 调用textTracks[0].mode = "showing") - 只有当
kind="subtitles"且mode === "showing"时,字幕才会真正渲染;mode初始值通常是"disabled",哪怕有default
如何让字幕一加载就显示(JS 强制启用)
想绕过用户手动操作,就得用 JS 主动设置字幕轨道模式。注意:这必须在轨道加载完成(load 事件)后执行,否则 textTracks 可能为空或未就绪。
- 监听
loadeddata或canplay事件比DOMContentLoaded更可靠,因为<track>是异步加载的 - 对每个
subtitles类型轨道,检查其kind和mode,再设为"showing":video.addEventListener('loadeddata', () => { const track = Array.from(video.textTracks).find(t => t.kind === 'subtitles' && t.language === 'zh'); if (track) track.mode = 'showing'; }); - 不要依赖
default属性做逻辑判断——它不保证mode初始值,有些浏览器甚至会忽略它
常见错误:字幕文件加载失败却不报错
<track> 的 src 加载失败时,浏览器通常静默失败,既不抛异常也不触发 error 事件,导致你以为字幕就绪了,其实根本没加载进来。
- 检查 Network 面板确认 VTT 文件返回 200 且 Content-Type 是
text/vtt(不是text/plain或application/octet-stream) - VTT 文件首行必须是
WEBVTT(严格大小写,前后不能有空格或 BOM) - 时间戳格式错误(如用逗号代替点、缺少双箭头
-->)、编码不是 UTF-8(含 BOM)都会导致整个轨道被丢弃 - 用
console.log(video.textTracks)查看track.readyState:0=not loaded, 1=loading, 2=loaded, 3=failed —— 但这个值在 Chrome 中常卡在 1 或 2,不可靠
移动端 Safari 的特殊限制
iOS Safari 对自动显示字幕更保守:即使 JS 设置了 mode = "showing",只要视频尚未播放(即未触发用户手势),字幕仍不会出现。
立即学习“前端免费学习笔记(深入)”;
- 必须在用户真实交互(如点击播放按钮)后的事件处理函数中调用
track.mode = "showing" - 不能在
autoplay触发的play事件里设,因为 autoplay 在 iOS 上受限,且此时上下文可能无权限 - 如果用了
playsinline,确保 video 元素在 viewport 内且尺寸足够(至少 200×150px),否则某些 iOS 版本会禁用字幕渲染
textTracks 列表里都看不到它。



















