srclang 属性必须设置且符合BCP 47规范,否则浏览器(如Chrome、Safari)会忽略字幕轨道;其值用于语言匹配和自动启用,与label分工明确,非法值会导致readyState为0且无报错。

srclang 属性必须写,否则浏览器可能忽略字幕轨道
浏览器(尤其是 Chrome 和 Safari)在解析 元素时,若缺少 srclang,会直接跳过该轨道,即使 kind="subtitles" 和 src 都正确。这不是“可选”,而是实际生效的硬性前提。
常见错误现象: 加载后字幕不显示,开发者工具里也看不到该轨道被注册。
-
srclang值必须是有效的 BCP 47 语言标签,比如"zh"、"zh-Hans"、"en-US"、"ja" - 不能写成自然语言(如
"chinese"或"Chinese (Simplified)"),浏览器不识别 - 大小写不敏感,但惯例全小写;带区域子标签时建议保留(如
"zh-Hans"比"zh"更明确)
srclang 和 label 属性分工不同,别混用
srclang 是机器可读的语言标识,用于匹配用户系统语言偏好或 video.textTracks[0].language 查询;label 是给人看的显示名,用于控制菜单中显示的文字(如“中文(简体)”、“English”)。
典型误用: 看似合理,但若用户系统语言设为 en-US,浏览器默认不会自动启用该轨道——因为启用逻辑依赖 srclang 匹配,而非 label 内容。
- 多语言字幕共存时,
srclang必须互异(如"en"、"zh"、"ja"),否则浏览器可能只取其一 -
label可以重复(虽不推荐),但srclang重复会导致行为不可控 - 如果想让某条轨道默认启用,需额外加
default属性,仅靠srclang不触发自动选择
srclang 值影响字幕轨道的自动匹配逻辑
当用户未手动切换字幕,且视频设置了 default,浏览器仍会参考 srclang 和系统语言做 fallback:比如用户系统语言是 zh-Hans,页面有 srclang="zh" 和 srclang="zh-Hans" 两条轨道,多数浏览器优先匹配更精确的 zh-Hans。
- 匹配规则遵循 RFC 4647 的“基本过滤算法”,不是简单字符串相等:例如
srclang="zh"可匹配zh-Hans、zh-CN,但srclang="zh-Hans"不会匹配zh - 若需最大兼容,对简体中文建议同时提供
srclang="zh-Hans"和srclang="zh"两条轨道(注意避免重复加载同一文件) - 服务端生成
时,别硬编码srclang,应从字幕文件名或元数据中提取真实语言码
srclang 错误值导致 track.readyState 为 0 或无法加载
部分浏览器(如旧版 Edge、某些 Android WebView)遇到非法 srclang(如空字符串、含空格、含下划线但不符合 BCP 47 格式)时,会静默失败:轨道对象存在但 readyState === 0,src 不发起请求,控制台也无报错。
调试技巧:在控制台执行 video.textTracks 查看轨道列表,再逐个检查 track.language 是否为空或为 "" —— 这往往就是 srclang 解析失败的信号。
- 合法值示例:
"en"、"pt-BR"、"ko"、"und"(未知语言) - 非法值示例:
"Chinese"、"zh_CN"(下划线应为短横)、"zh-"(不完整)、"" - VTT 文件本身不声明语言,一切以
为准;别指望浏览器从文件内容推测
真正容易被忽略的是:哪怕你用了正确的语言代码,只要父 元素还没插入 DOM,或 在 video.load() 之后才动态添加,srclang 也可能失效——必须确保 是在 video 初始化阶段就存在的静态 HTML 节点,或通过 video.addTextTrack() 手动创建并显式设置 language 属性。










