HTML5 Video Player无法加载.vtt字幕轨道的问题求助

问题代码与现象 #

HTML代码 #

<video controls>
  <source src="../assets/video/sample.mp4" type="video/mp4" />
  <track
    src="../assets/video/sample.vtt"
    kind="subtitles"
    srclang="en"
    label="English"
  />
</video>

VTT文件内容 #

WEBVTT

00:00:00.500 --> 00:00:02.000
The Web is always changing

00:00:02.500 --> 00:00:04.300
and the way we access it is changing

出现的问题 #

• 本地运行：视频正常加载，点击字幕按钮选择English时，控制台报404错误：GET http://localhost:8080/assets/video/sample.vtt 404 (Not Found)
• 服务器部署：无报错，但存在以下问题：
  • 字幕无法显示在视频上
  • Chrome浏览器中视频播放器的字幕按钮直接消失
  • 其他浏览器保留字幕按钮，但字幕依旧不显示
• 服务器网络请求排查：sample.vtt的请求URL正确且返回200状态码，但响应内容是网站index.html的完整代码（index.html存放在完全独立的文件夹中）

解决方案 #

1. 修正服务器路由规则 #

服务器返回index.html而非vtt文件，说明路由配置把未匹配的请求都重定向到了index.html（常见于SPA单页应用的默认配置）。需要：

• 确认.vtt文件的实际存储路径，确保和HTML中src属性的路径完全匹配
• 修改服务器路由，让.vtt、.mp4这类静态资源请求直接返回对应文件，不被SPA路由拦截：
  • Nginx示例配置：

    # 优先处理静态资源
    location ~* \.(vtt|mp4|css|js)$ {
      root /path/to/your/project/static;
      expires 30d;
    }
    # SPA路由规则放在后面
    location / {
      try_files $uri $uri/ /index.html;
    }
    

  • React/Vue等框架项目：确保打包配置将视频、vtt文件标记为静态资源，避免被路由规则捕获

2. 配置正确的MIME类型 #

服务器必须为.vtt文件返回text/vtt的MIME类型，否则浏览器无法识别为字幕文件：

• Nginx：在http或server块中添加：

  types {
    text/vtt vtt;
  }
  

• Apache：在.htaccess或主配置文件中添加：

  AddType text/vtt .vtt
  

3. 本地环境404问题修复 #

本地出现404，按以下步骤排查：

• 核对../assets/video/sample.vtt的相对路径：以当前HTML文件所在位置为基准，确认vtt文件的实际位置
• 检查本地开发服务器是否正确托管了assets文件夹，确保静态资源可被正常访问

4. 验证VTT文件格式 #

确认VTT文件格式无错误：

• 第一行必须是WEBVTT，无多余空格或特殊字符
• 时间戳的箭头-->前后必须保留空格
• 文件编码为UTF-8，且无BOM头（可通过记事本、VS Code等编辑器查看并调整）

内容的提问来源于stack exchange，提问作者Josh Halpern