ModernZ不显示、菜单没反应?常见故障排查与解决方案完整清单

原创2026-10-12 16:32:441,869 阅读
文章标签:UI组件音视频桌面应用插件系统

ModernZ不显示、菜单没反应?常见故障排查与解决方案完整清单

如果你在使用 ModernZ(mpv 播放器的一套现代化 OSC 控制界面)时遇到"界面不显示""按钮点了没反应""菜单打不开"等问题,这篇 ModernZ 故障排查指南可以帮你快速定位原因。全文不需要阅读代码,跟着清单逐项核对即可解决绝大多数问题。

🧭 第一步:检查安装位置是否正确

"OSC 完全不显示"最常见的原因就是文件放错了目录。请先对照下表核对(路径均在 mpv 配置目录下):

文件 正确位置 说明
modernz.lua scripts/ 核心脚本,缺它整个界面都不会出现
modernz-icons.ttf fonts/ 图标字体,缺失时按钮会变成乱码方块
modernz.conf script-opts/ 配置文件,放错位置时所有自定义设置都不生效
modernz-locale.json(可选) script-opts/ 多语言包,中文界面需要它

各平台 mpv 配置目录位置:

Linux:   ~/.config/mpv/
Windows: C:/Users/用户名/AppData/Roaming/mpv/
macOS:   ~/Library/Application Support/mpv/

另外,别忘了在 mpv.conf 中添加 osc=no 关闭 mpv 自带的 OSC,否则两个界面会互相顶替。

🚦 ModernZ 不显示?排查这 5 个可见性开关

ModernZ 默认"鼠标动一下才显示、停几秒自动隐藏",如果你希望它常驻却始终看不到,请依次检查 docs/USER_OPTS.md 中的这些选项:

  1. 可见性模式被设为隐藏 modernz.conf 中的 visibility 选项控制初始显隐模式(never / auto / always,见 modernz.conf#L329-L333)。临时看不出来?在 input.conf 中绑定快捷键手动切换:

    v   script-binding modernz/visibility        # 循环切换可见模式
    x   script-message-to modernz osc-show        # 强制显示
    y   script-message-to modernz osc-hide        # 强制隐藏
    
  2. 当前窗口模式被关闭了 showwindowed=no 会导致窗口模式下不显示,showfullscreen=no 则反过来。两者都设为 yes 最稳妥。

  3. 死区太大,鼠标"够不着" deadzonesize 决定窗口中有多大区域不响应鼠标移动(默认 0.75,即窗口边缘 75% 区域内的移动都会触发,中心区域无效)。若你习惯在画面正中移动鼠标,可适当调小该值,或把 minmousemove 设为 0。

  4. 隐藏超时太快 hidetimeout 默认 1500 毫秒(见 modernz.conf#L31-L45),如果觉得界面一闪而过,可以调大到 3000 以上,或配合 keeponpause 在暂停时保持显示。

  5. 脚本根本没加载成功 启动 mpv 后看终端日志是否有报错。ModernZ 需要较新的 mpv 版本,版本过旧是"界面消失"和"菜单失灵"共同的头号原因,建议先升级 mpv 再排查其他项。

🖱️ 按钮、菜单没反应?大概率是 mpv 版本问题

ModernZ 的交互菜单(播放列表、字幕、音轨、章节、音频设备选择)依赖 mpv 内置的 console.lua 与 select.lua 模块,仅 mpv v0.39 及以上版本支持。

判断方法:点击字幕或播放列表按钮后,如果只闪出简单文本甚至完全没反应,基本可断定版本过旧。

解决方案:

  • ✅ 推荐:升级到最新 mpv 版本,所有菜单功能即恢复(细节见 docs/INTERACTIVE_MENUS.md)
  • ⏳ 临时过渡:在 script-opts/modernz.conf 中添加下面这段简化功能,先用着再慢慢升级:
title_mbtn_left_command=show-text ${filename}
playlist_mbtn_left_command=show-text ${playlist} 3000
audio_track_mbtn_left_command=cycle audio
sub_track_mbtn_left_command=cycle sub
chapter_title_mbtn_left_command=show-text ${chapter-list} 3000

如果确认按钮本身没被隐藏(如 subtitles_button=yes、playlist_button=yes 等均为 yes),但点击仍无反应,可再检查 input.conf 中是否有快捷键绑定"占用"了对应的鼠标事件。各按钮左右键/中键/滚轮的完整对应关系,可查阅 docs/CONTROLS.md。

🎨 界面残缺、图标乱码?检查字体与配置

症状 可能原因 解决
按钮显示为方块/问号 modernz-icons.ttf 未放入 fonts/ 目录 重新放置字体文件后重启 mpv
所有按钮消失只剩进度条 配置中多个 *_button=no 对照 modernz.conf#L126-L192 恢复为 yes
中文显示为英文 缺少语言包 将 modernz-locale.json 放入 script-opts/,并在 modernz.conf 中设 language=zh
修改配置无效果 modernz.conf 放在了错误目录 确认位于 script-opts/ 下,文件名必须一字不差
界面过小/过大 缩放或布局设置 调整 scalewindowed、scalefullscreen,或换用 layout=compact 等布局

📋 一键自查清单

按顺序打勾,5 分钟定位问题:

  • [ ] mpv.conf 中已有 osc=no
  • [ ] modernz.lua 在 scripts/,modernz-icons.ttf 在 fonts/
  • [ ] modernz.conf 在 script-opts/ 且文件名完全正确
  • [ ] mpv 版本 ≥ v0.39(菜单功能必需)
  • [ ] visibility 不是 never,showwindowed / showfullscreen 为 yes
  • [ ] 需要中文界面时,语言包和 language=zh 都已配置
  • [ ] 终端启动日志中无报错信息

🛠️ 都试过还不行?收集日志再反馈

按照 docs/FAQ.md 的官方建议:

  1. 先换 mpv 自带 OSC 验证——若自带 OSC 也异常,问题多半出在 mpv 本身而非 ModernZ
  2. 复现时导出日志:mpv sample.mp4 --log-file=output.txt
  3. 提交反馈时附上日志文件(不要粘贴内容),并写清完整复现步骤

📚 相关文档速查

💡 小结:ModernZ 故障九成集中在"文件放错位置"与"mpv 版本过旧"两点上,先核对安装目录和版本,再对照可见性选项逐项排查,基本都能迎刃而解。

登录后查看全文
ModernZ