IPTVnator 结构化 Video.js/VHS 播放诊断公认证据边界、阶段映射与分类优先级设计【免费下载链接】iptvnator:tv: Cross-platform IPTV player application with multiple features, such as support of m3u and m3u8 playlists, favorites, TV guide, TV archive/catchup and more.项目地址: https://gitcode.com/GitHub_Trending/ip/iptvnatorIPTVnator 的默认 Web 播放器是 Video.js其 HLS/DASH 能力来自捆绑的videojs/http-streaming下称 VHS。本文基于设计文档 2026-07-31-structured-videojs-vhs-diagnostics-design.md 与仓库中的对应实现完整讲解如何为 Video.js/VHS 终态错误建立一条“最小化、白名单、防泄漏”的结构化诊断证据边界VhsPlaybackEvidence包括版本锁定的videojs.Error允许清单、阶段映射、分类优先级、运行时事件顺序、组件接线与 UI 输出格式。读完本文你可以理解该诊断边界为什么刻意拒绝 VHS 内部状态并能在仓库源码中找到每一条规则的落点。背景Video.js 路径为何需要独立的证据边界IPTVnator 的浏览器播放诊断此前经历了两步演进PR #1314 让通用原生播放诊断保留 Video.js 的 HTTP 状态码与metadata.errorType并且不再把含糊的MediaErrorcode 4 当作编解码codec证据PR #1316 为 HTML5 与 ArtPlayer 引擎新增了独立的 hls.js 结构化证据契约。但 Video.js 仍然是默认 Web 播放器而它的 HLS/DASH 实现是VHS 而不是 hls.js因此 PR #1316 的 hls.js 证据契约HlsPlaybackEvidence并不适用于它。这条路径此前只能依赖通用原生分类器存在一个具体的误导场景VHS 会把“没有 code 的通用内部对象错误”和“字符串错误”提升为 code 3MEDIA_ERR_DECODE再调用player.error()其中包括终态的 “no available playlists” 路径——这会被误诊为媒体解码错误。本设计的目标之一就是纠正这个 code 3 的误诊。依赖版本审计版本锁定的前提设计文档对安装依赖与上游 tag 做了逐一比对这是整个边界“版本锁定”策略的依据工作区安装 Video.js8.23.9、捆绑 VHS3.17.5此外还有一个与主播放器无关、嵌套在旧版 aspect-ratio 插件下的 Video.js7.21.7/ VHS2.16.3组合应用导入的是根 Video.js8.23.9构建其 package 声明 VHS^3.17.5pnpm 实际解析到3.17.5审计将安装源码与上游精确 tag 对比Video.jsv8.23.9commit81b3cb429fae8dd00659ac5d3b0b1d2d20a283cb、VHSv3.17.5commita9f9d7ac0264b373f14da1bb2f2e7fe8f2775c4f安装的 VHSerror-codes.js、videojs-http-streaming.js、playlist-controller.js与 tag 源码一致。这意味着边界所依赖的公开 API 面videojs.Error导出值、player.error()、player.tech().vhs在锁定的版本上是确定可验证的而不是对某个“大概率存在”的 API 的猜测。设计目标与非目标设计文档明确划定了这条边界要做什么、不做什么这个划分本身是理解后文所有实现取舍的钥匙。目标为终态 Video.js/VHS 错误新增一条最小化的白名单证据边界只保留公开 Video.jsMediaError字段与精确的公开videojs.Error标识符只分类精确确认过的值未知值一律保持unknown让可恢复的 VHS playlist/segment 处理不变成终态 IPTVnator 诊断绝不保留或渲染 VHS/服务方的 URL、请求头、xhr 对象、响应体、错误消息、凭据或任意元数据纠正 VHS 把通用内部对象/字符串提升为 code 3 的误导场景当 VHS 不是活跃 source handler 时保持通用原生 Video.js 播放行为完全不变。非目标不改动 PR #1316 的 hls.js 证据契约不做 Shaka 或 mpegts.js 的诊断重构不从消息文本或间接信号推断 CORS、混合内容、CSP、私有网络访问、编解码、DRM 或请求阶段不读取 VHS 的 playlist loader、segment loader、请求对象或其他私有实现状态不在生产环境中监听未成文的 VHS 重试/排除事件不做诊断历史、持久化、关联分析、流探测、自动故障切换或跨播放器推荐矩阵。方案权衡为什么选择公开错误边界设计文档评估了四个候选方案逐一否决的依据值得完整保留因为它直接解释了“为什么诊断代码里没有一行触碰 VHS 内部对象”。选定方案公开 Video.js 错误边界在公开的Player#error监听器中读取player.error()。当文档化的player.tech().vhs运行时属性存在时把错误清洗成小型的VhsPlaybackEvidence对象用videojs.Error导出的精确值校验metadata.errorType校验标准MediaErrorcode 与 HTTP 状态并且只在公开引擎标识符本身指明阶段时才推导 stage。这个方案不依赖 VHS 的 loader 或请求对象就能获得结构化证据同时让非 VHS 的通用 Video.js 错误继续走既有原生分类器。被否决的方案一观察 VHS xhr hooksVHS 公开文档了vhs.xhr.onRequest与onResponse但请求 hooks 要求把可变的请求对象与后来的终态错误做关联并且恰好在那个必须保持清洗的边界上暴露 URL、请求头、响应对象与服务方负载。更关键的是请求完成不等于终态播放结论——VHS 可能重试、排除某个 rendition 或自行恢复。因此否决。被否决的方案二读取 VHS loader 与重试事件安装的 VHS 实现内部携带精确的requestType、xhr、playlist、segment 与 key 上下文但这些对象及其事件顺序不属于文档化的稳定错误 API。依赖playlistController_、loader 错误对象、retryplaylist或excludeplaylist会破坏范围约束并让 VHS 版本升级变得高危。因此否决。被否决的方案三审计后止步如果公开 API 只暴露 PR #1314 已有的内容止步是正确选择。但审计找到了一个安全的增量videojs.Error是公开精确值白名单、player.error()在Player#error触发前已被赋值、活跃 VHS 可通过文档化的运行时属性检测。这足以结构化证据、抑制不安全的 message/metadata 保留并避免 code 3 的误诊——因此继续推进。版本锁定的公开证据清单Video.js8.23.9文档化并类型化了以下公开字段构成边界唯一允许读取的面player.error()返回当前 Video.jsMediaErrorMediaError.code承载标准 code 05MediaError.status是可选的插件提供状态MediaError.metadata.errorType预期与videojs.Error对齐Player#error在player.error_被替换为新MediaError之后发出VHS 活跃期间player.tech().vhs是文档化的 VHS 运行时属性。Video.js8.23.9公开导出的 14 个精确videojs.Error值白名单全集标识符语义归类networkbadstatus网络networkrequestfailed网络networkrequestaborted网络networkrequesttimeout网络networkbodyparserfailed网络streaminghlsplaylistparsererrorHLS 播放列表解析streamingdashmanifestparsererrorDASH 清单解析streamingcontentsteeringparsererror内容导引解析streamingvttparsererrorVTT 解析streamingfailedtoselectnextsegment段选择streamingfailedtodecryptsegment段解密streamingfailedtotransmuxsegment段转封装streamingfailedtoappendsegment段追加streamingcodecschangeerror编解码切换这份白名单在源码中逐字落地为 VhsPlaybackEngineType 常量对象并附unknown哨兵值VhsPlaybackUnknownEngineType。白名单是刻意版本锁定的仓库中的回归测试会把这份清单与实际安装的videojs.Error导出做比对因此依赖升级必须触发一次新的审计而不是静默接受新的引擎值。被拒绝的证据泄漏边界的另一半VHS3.17.5内部会附加requestType、uri、headers、error、xhr 对象、响应文本、playlist 对象与段上下文等字段。这些值可能包含凭据或服务方数据且公开 Video.jsErrorMetadata契约并不要求它们。边界不得读取或拷贝这些字段。具体被拒清单错误message——因为 VHS 的消息文本会内嵌请求 URLresponseText、响应数据与响应体请求/响应头任意元数据键或服务方对象requestType——它经player.error()的传播是实现细节不是文档化的稳定契约status 0——不作为 CORS 或浏览器访问受限的证据消息片段——不作为编解码、DRM、网络、访问或阶段证据。一个容易误解的点PlaybackDiagnostic.sourceUrl依然存在但只服务于既有的 Retry、Copy URL 与显式外部播放器工作流。Video.js/VHS 错误对象中的任何 URL 都不会被拷贝进证据或技术详情。VhsPlaybackEvidence证据契约证据对象只有五个字段全部经过值域校验任何一项不合法都退化为unknown/缺省字段类型与取值校验规则engineType一个精确的安装版videojs.Error值不在 14 值白名单内即为unknownmediaErrorCode标准MediaErrorcode 050 自定义、1 中断、2 网络、3 解码、4 源不支持、5 加密非整数或越界即为unknowndisposition固定terminal无 recoverable 证据对象stagemanifest/playlist/segment/unknown仅由精确引擎标识符推导httpStatus可选400599 的整数只从公开顶层MediaError.status拷贝模型定义见 VhsPlaybackEvidence 接口disposition枚举只含Terminal一个值——不存在 recoverable 证据对象IPTVnator 只在 Video.js 已存好最终错误、公开的Player#error事件到达之后才创建这条边界可恢复的 VHS 处理留在 VHS 内部完成不产生任何终态诊断。实现证据工厂函数的逐项清洗仓库实现 createVhsPlaybackEvidence 与文档契约一一对应export function createVhsPlaybackEvidence( error: NativePlaybackErrorInput ): VhsPlaybackEvidence { const engineType getEngineType(error.metadata?.errorType); const httpStatus getHttpStatus(error.status); const evidence: VhsPlaybackEvidence { engineType, mediaErrorCode: getMediaErrorCode(error.code), disposition: VhsPlaybackDisposition.Terminal, stage: getStage(engineType), }; return httpStatus undefined ? evidence : { ...evidence, httpStatus }; }三个校验辅助函数就是“白名单、整数、范围”三道闸getEngineType仅当值是字符串且命中Object.values(VhsPlaybackEngineType)集合时才采纳否则unknowngetMediaErrorCode仅当是 05 的整数时采纳getHttpStatus仅当是 400599 的整数时采纳否则整个字段缺省注意不是置 0 或置 null——字段直接不存在。由于输入类型 NativePlaybackErrorInput 的字段全部是可选且unknown友好的code?、status?、metadata?.errorType函数签名层面就无法让 VHS 的内部结构xhr、playlist、headers进入证据——它们根本没有类型上的通道。阶段映射只信引擎标识符不信内部元数据stage 只由精确的公开引擎标识符推导映射表如下实现见 getStage引擎标识符stagestreaminghlsplaylistparsererrorplayliststreamingdashmanifestparsererrormanifeststreamingfailedtoselectnextsegmentsegmentstreamingfailedtodecryptsegmentsegmentstreamingfailedtotransmuxsegmentsegmentstreamingfailedtoappendsegmentsegment所有网络标识符、内容导引/VTT 解析错误、编解码切换错误、未识别值unknown源码中前两类走独立分支四个段类错误收敛进一个SEGMENT_ENGINE_TYPES集合统一映射到segment。这里有一条刻意的设计决策网络错误即使内部元数据恰好携带requestType: hls-playlist、hls-segment或hls-key也保持 stage 为unknown。公开错误契约并不保证这些值边界拒绝用实现细节换取“看起来更精确”的阶段标注。classifyVhsPlaybackIssue分类优先级诊断分类器 classifyVhsPlaybackIssue 先调用createVhsPlaybackEvidence生成证据再按固定优先级求诊断码最后以source: vhs生成PlaybackDiagnostic证据挂在诊断对象的vhs字段上。优先级从高到低校验通过的 HTTP 4xx/5xx 状态 →network-error精确的公开网络错误类型 →network-error标准MediaErrorcode 2 →network-error精确的streamingfailedtodecryptsegment→drm-or-encryption标准MediaErrorcode 5 →drm-or-encryption已知的浏览器不兼容源容器仍可产生unsupported-container其余一切 →unknown-playback-error。其中最关键的一条否定规则是通用的 VHS code 3 不产生media-decode-error。VHS 在调用player.error()之前会把没有 code 的对象错误和字符串错误赋 code 3包括终态的 “no available playlists” 路径。所以在 VHS 路径上code 3 单独不足以作为解码证据。边界同样明确“不做什么分类”不从编解码切换、转封装、追加错误或消息文本推断编解码不兼容不从密钥请求/加载失败推断 DRM不从 status 0 或通用请求失败推断浏览器访问受限不从 code 3 单独推断媒体解码失败。对比之下没有活跃 VHS 的通用 Video.js 播放仍走既有原生分类器classifyNativePlaybackIssue路径因此原生 code 3 依然是media-decode-error。两条路径的分流条件只有“player.tech().vhs是否存在且错误是 Video.js 错误”这一条。运行时与事件顺序为什么监听器里能读到最终错误VHS3.17.5在公开终态错误之前内部已经处理了大量可恢复失败失败的 rendition 可被排除并改选其他 rendition单个有限次排除的 rendition 会被重试之前被排除的 rendition 可以重新纳入段超时可触发 ABR 恢复被中止的段请求按非错误忽略只有不可恢复的 playlist-controller 错误才会走到player.error(...)。Video.js8.23.9的行为是先构造并存入MediaError替换player.error_再同步触发Player#error。因此组件在自己的error监听器内读取player.error()拿到的就是最终错误可以直接标记为终态。IPTVnator 不订阅任何 VHS 内部恢复事件——可恢复处理全部留在 VHS 内诊断边界只在“真的终态”时介入。组件接线与 UI 输出VjsPlayerComponent诊断接线见 vjs-playback-diagnostics.ts只保留一个Player#error监听器处理顺序是先读player.error()读不到再回退到原生 video 错误通过文档化的player.tech().vhs运行时属性检测活跃 VHS活跃 VHS 且是 Video.js 错误 → 调用classifyVhsPlaybackIssue否则保持既有classifyNativePlaybackIssue路径恰好发出一条终态诊断。组件不检查playlistController_、loader、xhr hooks、请求类型、重试事件或错误消息。UI 侧新增一条确定性的 Video.js/VHS 技术详情摘要其格式为stageunknown · typenetworkbadstatus · code4 · dispositionterminal · HTTP 503摘要只由VhsPlaybackEvidence的字段拼装永不包含 Video.js 消息文本或任意元数据。既有的诊断标题、描述、HTTP 徽标、Retry、Copy URL 与显式 MPV/VLC 操作保持不变不需要新的翻译键或布局改动。测试策略与验证范围设计文档要求测试驱动开发TDD测试矩阵覆盖把白名单与实际安装的videojs.Error导出比对版本锁定回归在真实 Video.js 播放器上设置错误、从其error监听器读取player.error()验证真实公开事件顺序使用安装运行时形态的 VHS 错误覆盖 5xx、请求失败、超时、播放列表解析、段解密、通用 code 3、未知服务方元数据等场景证明 URL、请求头、响应数据、消息、凭据、请求类型与任意元数据无法穿过边界或出现在渲染详情里证明只有精确的公开网络/解密值影响分类证明活跃 VHS 下的通用 code 3 保持unknown而非 VHS 的原生 code 3 仍是媒体解码诊断证明组件把活跃 VHS 错误路由进结构化边界、让通用 Video.js 错误留在原生路径证明技术详情只渲染清洗后的 VHS 证据。对应的证据工厂测试位于 vhs-playback-evidence.util.spec.ts。验证目标是完整的ui-playback单测 target、其 lint target、web typecheck、i18n 校验、release note 校验以及仓库 test-impact 流程。不需要 E2E播放工作流、控制条、路由与集成生命周期均未变化改动被限定在既有终态错误边界与技术详情内部。文档与发布说明的落地该设计的收尾动作包括两处见设计文档“Documentation And Release Note”一节及实施计划 2026-07-31-structured-videojs-vhs-diagnostics.md更新 docs/architecture/embedded-inline-playback.md——浏览器播放诊断契约的权威文档把 VHS 边界并入契约描述新增一条fix(playback)类型的发布说明——因为用户收到的是更准确的默认播放器诊断与更安全的 technical details。小结这条 Video.js/VHS 诊断边界的设计核心可以概括为三点证据面只取版本审计过的公开 APIplayer.error()、metadata.errorType白名单、顶层status拒绝面封死一切可能携带 URL、凭据与服务方负载的内部字段分类规则只在精确值上下结论、其余一律unknown。由此IPTVnator 在不触碰 VHS 私有实现、不依赖未成文事件的前提下既修掉了 code 3 的误诊又把技术详情的输出限制在了可确定性渲染的五个字段上——这是它可以直接作为 LLM/Agent 可读诊断契约的结构性原因。【免费下载链接】iptvnator:tv: Cross-platform IPTV player application with multiple features, such as support of m3u and m3u8 playlists, favorites, TV guide, TV archive/catchup and more.项目地址: https://gitcode.com/GitHub_Trending/ip/iptvnator创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
IPTVnator 结构化 Video.js/VHS 播放诊断：公认证据边界、阶段映射与分类优先级设计
IPTVnator 结构化 Video.js/VHS 播放诊断公认证据边界、阶段映射与分类优先级设计【免费下载链接】iptvnator:tv: Cross-platform IPTV player application with multiple features, such as support of m3u and m3u8 playlists, favorites, TV guide, TV archive/catchup and more.项目地址: https://gitcode.com/GitHub_Trending/ip/iptvnatorIPTVnator 的默认 Web 播放器是 Video.js其 HLS/DASH 能力来自捆绑的videojs/http-streaming下称 VHS。本文基于设计文档 2026-07-31-structured-videojs-vhs-diagnostics-design.md 与仓库中的对应实现完整讲解如何为 Video.js/VHS 终态错误建立一条“最小化、白名单、防泄漏”的结构化诊断证据边界VhsPlaybackEvidence包括版本锁定的videojs.Error允许清单、阶段映射、分类优先级、运行时事件顺序、组件接线与 UI 输出格式。读完本文你可以理解该诊断边界为什么刻意拒绝 VHS 内部状态并能在仓库源码中找到每一条规则的落点。背景Video.js 路径为何需要独立的证据边界IPTVnator 的浏览器播放诊断此前经历了两步演进PR #1314 让通用原生播放诊断保留 Video.js 的 HTTP 状态码与metadata.errorType并且不再把含糊的MediaErrorcode 4 当作编解码codec证据PR #1316 为 HTML5 与 ArtPlayer 引擎新增了独立的 hls.js 结构化证据契约。但 Video.js 仍然是默认 Web 播放器而它的 HLS/DASH 实现是VHS 而不是 hls.js因此 PR #1316 的 hls.js 证据契约HlsPlaybackEvidence并不适用于它。这条路径此前只能依赖通用原生分类器存在一个具体的误导场景VHS 会把“没有 code 的通用内部对象错误”和“字符串错误”提升为 code 3MEDIA_ERR_DECODE再调用player.error()其中包括终态的 “no available playlists” 路径——这会被误诊为媒体解码错误。本设计的目标之一就是纠正这个 code 3 的误诊。依赖版本审计版本锁定的前提设计文档对安装依赖与上游 tag 做了逐一比对这是整个边界“版本锁定”策略的依据工作区安装 Video.js8.23.9、捆绑 VHS3.17.5此外还有一个与主播放器无关、嵌套在旧版 aspect-ratio 插件下的 Video.js7.21.7/ VHS2.16.3组合应用导入的是根 Video.js8.23.9构建其 package 声明 VHS^3.17.5pnpm 实际解析到3.17.5审计将安装源码与上游精确 tag 对比Video.jsv8.23.9commit81b3cb429fae8dd00659ac5d3b0b1d2d20a283cb、VHSv3.17.5commita9f9d7ac0264b373f14da1bb2f2e7fe8f2775c4f安装的 VHSerror-codes.js、videojs-http-streaming.js、playlist-controller.js与 tag 源码一致。这意味着边界所依赖的公开 API 面videojs.Error导出值、player.error()、player.tech().vhs在锁定的版本上是确定可验证的而不是对某个“大概率存在”的 API 的猜测。设计目标与非目标设计文档明确划定了这条边界要做什么、不做什么这个划分本身是理解后文所有实现取舍的钥匙。目标为终态 Video.js/VHS 错误新增一条最小化的白名单证据边界只保留公开 Video.jsMediaError字段与精确的公开videojs.Error标识符只分类精确确认过的值未知值一律保持unknown让可恢复的 VHS playlist/segment 处理不变成终态 IPTVnator 诊断绝不保留或渲染 VHS/服务方的 URL、请求头、xhr 对象、响应体、错误消息、凭据或任意元数据纠正 VHS 把通用内部对象/字符串提升为 code 3 的误导场景当 VHS 不是活跃 source handler 时保持通用原生 Video.js 播放行为完全不变。非目标不改动 PR #1316 的 hls.js 证据契约不做 Shaka 或 mpegts.js 的诊断重构不从消息文本或间接信号推断 CORS、混合内容、CSP、私有网络访问、编解码、DRM 或请求阶段不读取 VHS 的 playlist loader、segment loader、请求对象或其他私有实现状态不在生产环境中监听未成文的 VHS 重试/排除事件不做诊断历史、持久化、关联分析、流探测、自动故障切换或跨播放器推荐矩阵。方案权衡为什么选择公开错误边界设计文档评估了四个候选方案逐一否决的依据值得完整保留因为它直接解释了“为什么诊断代码里没有一行触碰 VHS 内部对象”。选定方案公开 Video.js 错误边界在公开的Player#error监听器中读取player.error()。当文档化的player.tech().vhs运行时属性存在时把错误清洗成小型的VhsPlaybackEvidence对象用videojs.Error导出的精确值校验metadata.errorType校验标准MediaErrorcode 与 HTTP 状态并且只在公开引擎标识符本身指明阶段时才推导 stage。这个方案不依赖 VHS 的 loader 或请求对象就能获得结构化证据同时让非 VHS 的通用 Video.js 错误继续走既有原生分类器。被否决的方案一观察 VHS xhr hooksVHS 公开文档了vhs.xhr.onRequest与onResponse但请求 hooks 要求把可变的请求对象与后来的终态错误做关联并且恰好在那个必须保持清洗的边界上暴露 URL、请求头、响应对象与服务方负载。更关键的是请求完成不等于终态播放结论——VHS 可能重试、排除某个 rendition 或自行恢复。因此否决。被否决的方案二读取 VHS loader 与重试事件安装的 VHS 实现内部携带精确的requestType、xhr、playlist、segment 与 key 上下文但这些对象及其事件顺序不属于文档化的稳定错误 API。依赖playlistController_、loader 错误对象、retryplaylist或excludeplaylist会破坏范围约束并让 VHS 版本升级变得高危。因此否决。被否决的方案三审计后止步如果公开 API 只暴露 PR #1314 已有的内容止步是正确选择。但审计找到了一个安全的增量videojs.Error是公开精确值白名单、player.error()在Player#error触发前已被赋值、活跃 VHS 可通过文档化的运行时属性检测。这足以结构化证据、抑制不安全的 message/metadata 保留并避免 code 3 的误诊——因此继续推进。版本锁定的公开证据清单Video.js8.23.9文档化并类型化了以下公开字段构成边界唯一允许读取的面player.error()返回当前 Video.jsMediaErrorMediaError.code承载标准 code 05MediaError.status是可选的插件提供状态MediaError.metadata.errorType预期与videojs.Error对齐Player#error在player.error_被替换为新MediaError之后发出VHS 活跃期间player.tech().vhs是文档化的 VHS 运行时属性。Video.js8.23.9公开导出的 14 个精确videojs.Error值白名单全集标识符语义归类networkbadstatus网络networkrequestfailed网络networkrequestaborted网络networkrequesttimeout网络networkbodyparserfailed网络streaminghlsplaylistparsererrorHLS 播放列表解析streamingdashmanifestparsererrorDASH 清单解析streamingcontentsteeringparsererror内容导引解析streamingvttparsererrorVTT 解析streamingfailedtoselectnextsegment段选择streamingfailedtodecryptsegment段解密streamingfailedtotransmuxsegment段转封装streamingfailedtoappendsegment段追加streamingcodecschangeerror编解码切换这份白名单在源码中逐字落地为 VhsPlaybackEngineType 常量对象并附unknown哨兵值VhsPlaybackUnknownEngineType。白名单是刻意版本锁定的仓库中的回归测试会把这份清单与实际安装的videojs.Error导出做比对因此依赖升级必须触发一次新的审计而不是静默接受新的引擎值。被拒绝的证据泄漏边界的另一半VHS3.17.5内部会附加requestType、uri、headers、error、xhr 对象、响应文本、playlist 对象与段上下文等字段。这些值可能包含凭据或服务方数据且公开 Video.jsErrorMetadata契约并不要求它们。边界不得读取或拷贝这些字段。具体被拒清单错误message——因为 VHS 的消息文本会内嵌请求 URLresponseText、响应数据与响应体请求/响应头任意元数据键或服务方对象requestType——它经player.error()的传播是实现细节不是文档化的稳定契约status 0——不作为 CORS 或浏览器访问受限的证据消息片段——不作为编解码、DRM、网络、访问或阶段证据。一个容易误解的点PlaybackDiagnostic.sourceUrl依然存在但只服务于既有的 Retry、Copy URL 与显式外部播放器工作流。Video.js/VHS 错误对象中的任何 URL 都不会被拷贝进证据或技术详情。VhsPlaybackEvidence证据契约证据对象只有五个字段全部经过值域校验任何一项不合法都退化为unknown/缺省字段类型与取值校验规则engineType一个精确的安装版videojs.Error值不在 14 值白名单内即为unknownmediaErrorCode标准MediaErrorcode 050 自定义、1 中断、2 网络、3 解码、4 源不支持、5 加密非整数或越界即为unknowndisposition固定terminal无 recoverable 证据对象stagemanifest/playlist/segment/unknown仅由精确引擎标识符推导httpStatus可选400599 的整数只从公开顶层MediaError.status拷贝模型定义见 VhsPlaybackEvidence 接口disposition枚举只含Terminal一个值——不存在 recoverable 证据对象IPTVnator 只在 Video.js 已存好最终错误、公开的Player#error事件到达之后才创建这条边界可恢复的 VHS 处理留在 VHS 内部完成不产生任何终态诊断。实现证据工厂函数的逐项清洗仓库实现 createVhsPlaybackEvidence 与文档契约一一对应export function createVhsPlaybackEvidence( error: NativePlaybackErrorInput ): VhsPlaybackEvidence { const engineType getEngineType(error.metadata?.errorType); const httpStatus getHttpStatus(error.status); const evidence: VhsPlaybackEvidence { engineType, mediaErrorCode: getMediaErrorCode(error.code), disposition: VhsPlaybackDisposition.Terminal, stage: getStage(engineType), }; return httpStatus undefined ? evidence : { ...evidence, httpStatus }; }三个校验辅助函数就是“白名单、整数、范围”三道闸getEngineType仅当值是字符串且命中Object.values(VhsPlaybackEngineType)集合时才采纳否则unknowngetMediaErrorCode仅当是 05 的整数时采纳getHttpStatus仅当是 400599 的整数时采纳否则整个字段缺省注意不是置 0 或置 null——字段直接不存在。由于输入类型 NativePlaybackErrorInput 的字段全部是可选且unknown友好的code?、status?、metadata?.errorType函数签名层面就无法让 VHS 的内部结构xhr、playlist、headers进入证据——它们根本没有类型上的通道。阶段映射只信引擎标识符不信内部元数据stage 只由精确的公开引擎标识符推导映射表如下实现见 getStage引擎标识符stagestreaminghlsplaylistparsererrorplayliststreamingdashmanifestparsererrormanifeststreamingfailedtoselectnextsegmentsegmentstreamingfailedtodecryptsegmentsegmentstreamingfailedtotransmuxsegmentsegmentstreamingfailedtoappendsegmentsegment所有网络标识符、内容导引/VTT 解析错误、编解码切换错误、未识别值unknown源码中前两类走独立分支四个段类错误收敛进一个SEGMENT_ENGINE_TYPES集合统一映射到segment。这里有一条刻意的设计决策网络错误即使内部元数据恰好携带requestType: hls-playlist、hls-segment或hls-key也保持 stage 为unknown。公开错误契约并不保证这些值边界拒绝用实现细节换取“看起来更精确”的阶段标注。classifyVhsPlaybackIssue分类优先级诊断分类器 classifyVhsPlaybackIssue 先调用createVhsPlaybackEvidence生成证据再按固定优先级求诊断码最后以source: vhs生成PlaybackDiagnostic证据挂在诊断对象的vhs字段上。优先级从高到低校验通过的 HTTP 4xx/5xx 状态 →network-error精确的公开网络错误类型 →network-error标准MediaErrorcode 2 →network-error精确的streamingfailedtodecryptsegment→drm-or-encryption标准MediaErrorcode 5 →drm-or-encryption已知的浏览器不兼容源容器仍可产生unsupported-container其余一切 →unknown-playback-error。其中最关键的一条否定规则是通用的 VHS code 3 不产生media-decode-error。VHS 在调用player.error()之前会把没有 code 的对象错误和字符串错误赋 code 3包括终态的 “no available playlists” 路径。所以在 VHS 路径上code 3 单独不足以作为解码证据。边界同样明确“不做什么分类”不从编解码切换、转封装、追加错误或消息文本推断编解码不兼容不从密钥请求/加载失败推断 DRM不从 status 0 或通用请求失败推断浏览器访问受限不从 code 3 单独推断媒体解码失败。对比之下没有活跃 VHS 的通用 Video.js 播放仍走既有原生分类器classifyNativePlaybackIssue路径因此原生 code 3 依然是media-decode-error。两条路径的分流条件只有“player.tech().vhs是否存在且错误是 Video.js 错误”这一条。运行时与事件顺序为什么监听器里能读到最终错误VHS3.17.5在公开终态错误之前内部已经处理了大量可恢复失败失败的 rendition 可被排除并改选其他 rendition单个有限次排除的 rendition 会被重试之前被排除的 rendition 可以重新纳入段超时可触发 ABR 恢复被中止的段请求按非错误忽略只有不可恢复的 playlist-controller 错误才会走到player.error(...)。Video.js8.23.9的行为是先构造并存入MediaError替换player.error_再同步触发Player#error。因此组件在自己的error监听器内读取player.error()拿到的就是最终错误可以直接标记为终态。IPTVnator 不订阅任何 VHS 内部恢复事件——可恢复处理全部留在 VHS 内诊断边界只在“真的终态”时介入。组件接线与 UI 输出VjsPlayerComponent诊断接线见 vjs-playback-diagnostics.ts只保留一个Player#error监听器处理顺序是先读player.error()读不到再回退到原生 video 错误通过文档化的player.tech().vhs运行时属性检测活跃 VHS活跃 VHS 且是 Video.js 错误 → 调用classifyVhsPlaybackIssue否则保持既有classifyNativePlaybackIssue路径恰好发出一条终态诊断。组件不检查playlistController_、loader、xhr hooks、请求类型、重试事件或错误消息。UI 侧新增一条确定性的 Video.js/VHS 技术详情摘要其格式为stageunknown · typenetworkbadstatus · code4 · dispositionterminal · HTTP 503摘要只由VhsPlaybackEvidence的字段拼装永不包含 Video.js 消息文本或任意元数据。既有的诊断标题、描述、HTTP 徽标、Retry、Copy URL 与显式 MPV/VLC 操作保持不变不需要新的翻译键或布局改动。测试策略与验证范围设计文档要求测试驱动开发TDD测试矩阵覆盖把白名单与实际安装的videojs.Error导出比对版本锁定回归在真实 Video.js 播放器上设置错误、从其error监听器读取player.error()验证真实公开事件顺序使用安装运行时形态的 VHS 错误覆盖 5xx、请求失败、超时、播放列表解析、段解密、通用 code 3、未知服务方元数据等场景证明 URL、请求头、响应数据、消息、凭据、请求类型与任意元数据无法穿过边界或出现在渲染详情里证明只有精确的公开网络/解密值影响分类证明活跃 VHS 下的通用 code 3 保持unknown而非 VHS 的原生 code 3 仍是媒体解码诊断证明组件把活跃 VHS 错误路由进结构化边界、让通用 Video.js 错误留在原生路径证明技术详情只渲染清洗后的 VHS 证据。对应的证据工厂测试位于 vhs-playback-evidence.util.spec.ts。验证目标是完整的ui-playback单测 target、其 lint target、web typecheck、i18n 校验、release note 校验以及仓库 test-impact 流程。不需要 E2E播放工作流、控制条、路由与集成生命周期均未变化改动被限定在既有终态错误边界与技术详情内部。文档与发布说明的落地该设计的收尾动作包括两处见设计文档“Documentation And Release Note”一节及实施计划 2026-07-31-structured-videojs-vhs-diagnostics.md更新 docs/architecture/embedded-inline-playback.md——浏览器播放诊断契约的权威文档把 VHS 边界并入契约描述新增一条fix(playback)类型的发布说明——因为用户收到的是更准确的默认播放器诊断与更安全的 technical details。小结这条 Video.js/VHS 诊断边界的设计核心可以概括为三点证据面只取版本审计过的公开 APIplayer.error()、metadata.errorType白名单、顶层status拒绝面封死一切可能携带 URL、凭据与服务方负载的内部字段分类规则只在精确值上下结论、其余一律unknown。由此IPTVnator 在不触碰 VHS 私有实现、不依赖未成文事件的前提下既修掉了 code 3 的误诊又把技术详情的输出限制在了可确定性渲染的五个字段上——这是它可以直接作为 LLM/Agent 可读诊断契约的结构性原因。【免费下载链接】iptvnator:tv: Cross-platform IPTV player application with multiple features, such as support of m3u and m3u8 playlists, favorites, TV guide, TV archive/catchup and more.项目地址: https://gitcode.com/GitHub_Trending/ip/iptvnator创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考