track.readyState为0或1时不能设mode="showing",必须等其变为2(LOADED)才安全;需检查kind==="subtitles"且mode非"disabled",动态添加track需手动加载vtt内容或使用有效HTTP(S)地址。

track.readyState 为 0 或 1 时不能设 mode = "showing"
直接写 track.mode = "showing" 却没显示字幕,大概率是因为 track.readyState 还是 0(NONE)或 1(LOADING)。浏览器不会等资源加载完再执行 JS,此时设置无效,且不报错。
必须等状态变为 2(LOADED)才安全操作。常见错误是把 track 拿到就立刻赋值,尤其在动态插入 后立即遍历 video.textTracks 时——列表虽已更新,但轨道内容远未加载。
- 检查方式:
if (track.readyState === TextTrack.LOADED)或track.readyState === 2 - 不要只靠一次判断:
track可能还在加载中,需监听track.onload事件(注意不是video.onload) -
track.onerror也得监听,readyState === 3(ERROR)时说明 .vtt 文件 404、格式错误或 CORS 阻断
为什么 document.readyState === "interactive" 不能代替 track.readyState === 2
document.readyState 是页面级状态,track.readyState 是单个字幕文件的加载状态。两者完全无关。即使 DOM 已就绪(interactive), 仍可能因网络延迟、CORS 或路径错误卡在 LOADING 状态。
典型误用:在 DOMContentLoaded 回调里批量设置所有 track.mode,结果部分字幕始终不出现。
-
video.textTracks列表在解析完就存在,但track.readyState要等 .vtt 文件 HTTP 响应完成并解析成功才升为2 - 本地开发用
file://协议时,track.readyState几乎永远停在0—— 浏览器直接拒绝加载 .vtt,需起本地服务(如python3 -m http.server) - DevTools 的 Network 面板里搜
.vtt,确认返回 200;Console 查看是否有Failed to load resource
track.readyState === 2 后 mode 仍不生效?检查 kind 和用户启用状态
就算 readyState 是 2,track.mode = "showing" 也可能静默失败。根本原因有两个:
-
track.kind不是"subtitles"(比如写成"captions"或漏写),浏览器压根不把它当字幕处理,不会出现在播放器菜单里 - 该轨道从未被用户“启用”过:浏览器策略要求,JS 无法绕过用户授权强制显示字幕;必须先确保
track.mode !== "disabled",才能设为"showing" - 验证方式:
console.log(track.kind, track.mode, track.srclang),三者都得符合预期
真正可靠的自动化流程是:等 readyState === 2 → 检查 kind === "subtitles" → 若当前 mode === "disabled",先设为 "hidden" 再设 "showing"(部分浏览器对从 disabled 直接切 showing 有拦截)。
动态添加 track 后 readyState 不触发 onload 怎么办
用 JS 创建 document.createElement("track") 并 append 到 video 后,track.onload 事件经常不触发,readyState 也长期卡在 0。这不是 bug,而是规范行为:动态插入的 不会自动发起加载,除非你显式调用 track.track 属性触发初始化(但该属性只读)。
正确做法是:插入后手动 fetch .vtt 内容,再用 Blob URL + URL.createObjectURL() 赋给 track.src —— 注意:track.src **不支持 Blob URL**,这会静默失败。所以只能退而求其次:
- 把 .vtt 内容 fetch 下来,用
new VTTCue(...)手动构建TextTrackCue,再通过track.addCue()注入 - 或者,改用服务端渲染真实 URL(如
/api/vtt?lang=zh),确保track.src是可跨域访问的 HTTP(S) 地址 - 避免在
video未挂载到 DOM 前插入,否则加载逻辑可能被跳过
readyState 的坑不在值本身,而在它反映的是「浏览器是否认为资源已就绪」,而不是「你是否觉得它该就绪了」——中间隔着网络、CORS、编码、VTT 格式、DOM 插入时机整整五道墙。
前端入门到VUE实战笔记:立即使用
在学习笔记中,你将探索 前端 的入门与实战技巧!











