WebVTT格式字幕需正确配置video标签内track元素，路径可访问且服务化运行，时间戳格式合规，样式通过::cue控制。

字幕文件必须是 WebVTT 格式，不是 SRT 或 TXT

浏览器原生 <video></video> 标签只支持 .vtt 字幕文件，直接扔个 .srt 进去不会显示。SRT 需先转换：用在线工具（如 “srt to vtt converter”）或命令行工具 ffmpeg：

ffmpeg -i subtitles.srt subtitles.vtt

注意检查转换后的时间戳格式是否为 HH:MM:SS.mmm，且每段开头有合法的序号或空行——WebVTT 不要求序号，但禁止乱码和 UTF-8 BOM。

<track></track> 必须写在 <video></video> 内部，且紧贴在 <source></source> 之后

顺序错、位置错都会导致字幕不加载：

<video controls><br>  <source src="lesson.mp4" type="video/mp4"><br>  <track kind="subtitles" label="中文" srclang="zh" src="subtitle.zh.vtt" default><br></video>

• kind="subtitles" 是必须值，别写成 "captions"（那是给听障用户的带音效描述的）
• srclang 必须是合法语言标签，比如 zh、en，写 ch 或空值会失效
• default 属性只允许一个 <track></track> 拥有，否则全部被忽略

字幕文件路径必须可被浏览器直接 HTTP 访问，不能是本地 file://

开发时常见错误：双击 HTML 打开，字幕不显示——因为浏览器出于安全限制，拒绝从 file:// 加载 <track></track>。必须起一个本地服务：

htmlppt.skill

把任意文章或文档内容转换成精美的全屏翻页 HTML 演示文件（幻灯片风格）。当用户发来一篇文章、文档链接、Markdown 内容、或粘贴的文本，并且希望生成演示用的 HTML 时触发。支持任意内容来源：iWiki 链接、KM 链接、本地文件路径、直接粘贴的文本。生成的 HTML 文件保存到本地工作区，并通过企微直接发送给用户。触发词示例：帮我把这篇文章做成PPT、转成演示文档、生成HTML幻灯片、做个演示、转成可以演示的格式、article to deck、make a slide。

下载

• Python 3：python3 -m http.server 8000，然后访问 http://localhost:8000
• VS Code 安装 Live Server 插件，右键“Open with Live Server”
• 确保 src="subtitle.zh.vtt" 的路径是相对当前 HTML 文件的，比如字幕和 HTML 同目录就写对，若在 subtitles/ 下就得写 subtitles/subtitle.zh.vtt

调试字幕不显示？先看控制台有没有 Failed to load resource 或 DOMException: The element has no supported tracks

这两个错误最典型：

• 前者说明路径错了或服务器没返回 200（比如 Nginx 没配 vtt MIME 类型，需加 add_type text/vtt .vtt;）
• 后者通常是 <track></track> 放错位置，或 kind 值非法，或视频还没加载完就调用了 video.textTracks
• 手动验证：把 subtitle.zh.vtt 地址粘到浏览器地址栏，应能直接看到纯文本内容，且首行是 WEBVTT

字幕样式无法用 CSS 直接选中每行文字，只能通过 ::cue 伪元素控制，比如：

video::cue { color: yellow; font-size: 1.2em; }

但别指望它支持 flex 或复杂定位——底层渲染机制限制很大。

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