ModernZ不显示、菜单没反应?常见故障排查与解决方案完整清单
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 中的这些选项:
-
可见性模式被设为隐藏
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 # 强制隐藏 -
当前窗口模式被关闭了
showwindowed=no会导致窗口模式下不显示,showfullscreen=no则反过来。两者都设为yes最稳妥。 -
死区太大,鼠标"够不着"
deadzonesize决定窗口中有多大区域不响应鼠标移动(默认 0.75,即窗口边缘 75% 区域内的移动都会触发,中心区域无效)。若你习惯在画面正中移动鼠标,可适当调小该值,或把minmousemove设为 0。 -
隐藏超时太快
hidetimeout默认 1500 毫秒(见 modernz.conf#L31-L45),如果觉得界面一闪而过,可以调大到 3000 以上,或配合keeponpause在暂停时保持显示。 -
脚本根本没加载成功 启动 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 的官方建议:
- 先换 mpv 自带 OSC 验证——若自带 OSC 也异常,问题多半出在 mpv 本身而非 ModernZ
- 复现时导出日志:
mpv sample.mp4 --log-file=output.txt - 提交反馈时附上日志文件(不要粘贴内容),并写清完整复现步骤
📚 相关文档速查
- 用户选项手册(含布局、主题、颜色、位置等全部参数):docs/USER_OPTS.md
- 按钮交互手册(每个按钮的左/右/中键与滚轮功能):docs/CONTROLS.md
- 交互菜单与右键菜单说明:docs/INTERACTIVE_MENUS.md
- 附加脚本(暂停指示、画中窗、打开文件):extras/
💡 小结:ModernZ 故障九成集中在"文件放错位置"与"mpv 版本过旧"两点上,先核对安装目录和版本,再对照可见性选项逐项排查,基本都能迎刃而解。