诊断与故障排除
先执行：
/videoplayer diagnostics
记录 Minecraft、VideoPlayer、Java、后端、操作系统和架构；分享日志前删除 Cookie、令牌、代理凭据和签名 URL。
快速定位
| 症状 | 首要检查 | 处理 |
|---|---|---|
| 原版客户端看不到视频 | 是否安装客户端模组 | 安装匹配的 Fabric 模组；桥接插件不能替代客户端 |
| 加入时报告版本不匹配 | /vlcversion、Minecraft 与 JAR 后缀 | 使用同一目标版本的客户端和桥接 |
| 后端初始化失败 | /videoplayer boot、诊断中的库路径 | 重新选择 MPV/VLC，检查运行库和架构 |
| 原生库下载超时 | DNS、TLS、native.download-proxy | 配置可达代理或受控手工部署，不公开代理口令 |
| YouTube 无法解析 | yt-dlp 路径和版本 | 修正 native.mpv-ytdl-path 或更新托管版本 |
| 受限视频失败 | Cookie 有效期和账户权限 | 更新 youtube.cookies-file/浏览器认证 |
| 能观看但不能操作 | videoplayer.action.* | 补充最小权限，检查默认值是否被权限插件覆盖 |
| Residence 内不能创建 | 所有者、padd、VideoPlayer 权限 | 同时修正领地和插件权限 |
| 多人进度偏差 | 版本、后端、网络和同步权限 | 先统一版本，再请求同步或自动同步 |
| 屏幕变形/UV 错位 | 顶点顺序、数量、UV 和缩放 | 按闭合条带顺序重建，顶点不超过 64 |
服务端检查顺序
- 确认插件启用，没有依赖加载错误。
- 运行
/vlcversion，确认玩家客户端已握手。 - 检查权限插件和 Residence。
- 检查
config.yml中 backend/os/arch 与实际 JVM。 - 检查原生库、
yt-dlp、Cookie 文件的访问权限。 - 用简单、公开、无认证的测试直链隔离来源问题。
Folia/Luminol
不要把 folia-supported: true 当作排障结论。记录精确核心名称、Minecraft 版本和构建号；跨 Region 玩家问题应在真实目标核心复现，并与静态审查边界对照。