MAKO 不工作?终极排障清单与私有诊断报告生成全流程
MAKO 不工作?终极排障清单与私有诊断报告生成全流程
MAKO 是 Linux 游戏平台上的新一代 Vulkan 图形层,为 Steam Deck、Steam Machine 和桌面 Linux 带来 Lossless Scaling 帧生成、超分辨率缩放与着色器增强。当 MAKO 不工作时,不必盲目重装——本文提供一份按优先级排列的排障清单,并手把手教你走完"开启日志 → 复现问题 → 生成报告 → 私有提交"的诊断报告生成全流程,把问题一次性交给开发者。
排障前先自查:90% 的"不工作"都卡在这 3 步
MAKO 的激活逻辑很简单:游戏进程匹配 → 启动参数正确 → 功能开关生效。任何一环断裂都会表现为"装了但没反应"。
1️⃣ 确认游戏确实跑在 Vulkan 上
MAKO 只拦截 Vulkan 调用链:
- Windows 游戏走 Proton 时,确保 DXVK / VKD3D-Proton 已启用(默认即是);
- 模拟器请手动选择 Vulkan 后端;
- 纯 OpenGL 老游戏可能需要借助 Zink 转 Vulkan。
2️⃣ 确认启动参数完整复制
最典型的翻车方式是手敲启动参数时漏掉前缀。正确做法是从 MAKO Renderer Configuration 界面里完整复制生成的启动选项,粘贴进 Steam 启动项:
~/.local/bin/mako-launch %command%
⚠️ 终端启动时把
%command%替换为实际可执行文件;Decky 插件用户则使用/home/deck/.local/bin/mako-run %command%。
可以顺手验证层是否真的加载:
~/.local/bin/mako-launch vulkaninfo | grep -i VK_LAYER_MAKO_render
没有任何输出说明层根本没装好或环境不对;32 位游戏还需安装匹配的 32 位层。
3️⃣ 检查 Matched Processes 与 Restart 标记
- 只保存了 Profile 但没有匹配到游戏可执行文件,MAKO 不会激活——去配置界面核对 Matched Processes 是否指向游戏本体(而不是 Steam 或启动器);
- 带 Restart 标记的选项(如
Enable Frame-gen (Restart))必须在改完之后再启动一次游戏才生效。
详细对照见官方排障文档:engine/docs/TROUBLESHOOTING.md、Decky 版 plugin/docs/TROUBLESHOOTING.md。
功能开了却不生效?逐个排查高频配置坑
如果层已加载、进程也匹配了,但帧生成/缩放"毫无感觉",依次检查:
| 功能 | 前置条件 | 常见坑 |
|---|---|---|
| Frame Generation / LS1 | 需安装 Lossless Scaling(Steam 默认版)并配置有效 DLL 路径 | 没装 LS 却期望插帧生效 |
| MAKO Scaler / Shaders | 无需 Lossless Scaling | 游戏内分辨率没调低,看不到缩放效果 |
| 任意插帧功能 | 必须使用游戏所在的 GPU | 残留的 GPU 手动覆盖项 |
| HDR | 实验性功能,默认关闭 | 开了 HDR 却忘了关 Gamescope WSI |
💡 排查技巧:逐项单独测试——分别开关 V-Sync、只开缩放不开着色器、只开插帧——能快速定位是哪个环节在捣乱。
用一条命令验证配置文件
配置写坏了也会静默失效。仓库中的 validate 工具 提供了一条自检命令:
mako-cli validate --config ~/.config/mako-render/conf.toml
报错就直接暴露了配置文件问题;完整参数说明见 engine/mako-cli/。
私有诊断报告生成全流程:5 步搞定
上面的清单都走过还有问题?那就进入标准诊断流程。核心工具是 scripts/mako-diagnostics——它会把一次测试运行过滤成一份聚焦的、可分享的诊断报告,只保留 MAKO / Vulkan Loader / Gamescope WSI 相关行,并自动剔除无关日志。
注意选择你对应的安装方式文档:独立安装(
mako-launch)看 engine/docs/COLLECT_DIAGNOSTICS.md;MAKO Decky 插件(mako-run)看 plugin/docs/COLLECT_DIAGNOSTICS.md。
第 1 步:开启诊断日志
完全关闭游戏并先保存当前启动项(方便事后还原)。然后在现有启动项最前面加上两个诊断变量:
MAKO_PRESENT_DIAGNOSTICS=1 MAKO_PRESENT_DIAGNOSTICS_THRESHOLD_MS=25 ~/.local/bin/mako-launch %command%
Heroic / Lutris / Flatpak 用户则在游戏的环境变量里加入:
MAKO_PRESENT_DIAGNOSTICS=1
MAKO_PRESENT_DIAGNOSTICS_THRESHOLD_MS=25
终端启动可直接捕获完整输出:
MAKO_PRESENT_DIAGNOSTICS=1 MAKO_PRESENT_DIAGNOSTICS_THRESHOLD_MS=25 \
mako-launch your-game-command 2>&1 | tee "$HOME/Desktop/MAKO-renderer-session.log"
第 2 步:复现一次问题
启动游戏,完整复现一次异常现象(卡住、掉帧、画面错误均可),记下表现,然后彻底退出游戏。⚠️ 退出前先完成复现,且在开始下一次测试前就收集报告,否则日志会话会被覆盖。
第 3 步:生成诊断报告
桌面模式打开 Konsole 执行:
mako-diagnostics --lines 5000 all > "$HOME/Desktop/MAKO-diagnostics.txt" 2>&1
- 命令找不到时改用
~/.local/bin/mako-diagnostics(Decky 用户为/home/deck/.local/bin/mako-diagnostics); - 前面用终端
tee捕获过日志的,在--lines前追加--log "$HOME/Desktop/MAKO-renderer-session.log"; - 长会话后才出现的性能衰减:把
--lines 5000换成--lines 200000; - 报告出现在桌面,终端通常不打印任何内容,这属于正常现象。
需要按功能切片分析时,mako-diagnostics 还提供了一组预设:hdr、scaling、adaptive、recovery、performance、lifecycle、startup、layers、errors、all,可自由组合,例如 mako-diagnostics scaling adaptive。
第 4 步:还原配置
把启动项改回原样,删掉第 1 步添加的两个诊断变量,让游戏回到日常状态。
第 5 步:私有提交报告
- 打开
MAKO-diagnostics.txt,手动删去个人敏感信息(路径、用户名等); - 通过官方私有诊断表单提交(入口见上述两份 COLLECT_DIAGNOSTICS 文档),独立安装选 MAKO Renderer (standalone/direct installation),Decky 选 MAKO Decky (Decky Loader plugin),拿不准的选项一律选 Unknown;
- 🚫 两个红线:不要把日志公开贴到 issue 或论坛,不要附上
Lossless.dll。
对比测试的小技巧
排查画质或帧率回归时,每次改动后单独收集一份报告,并记录改了什么设置;尽量使用同一场景、同一游戏画质,HDR 相关对比还要记下游戏分辨率与显示器分辨率,开发者才能精准定位。
收尾:记住这个排障顺序
✅ 快速回忆路径:Vulkan 后端 → 启动参数 → 进程匹配 → 前置依赖(Lossless Scaling)→ 配置校验(mako-cli validate)→ 诊断报告(mako-diagnostics)。前四步解决大多数"不工作",最后两步把疑难杂症打包成专业报告交给团队——这正是 MAKO 项目把 COLLECT_DIAGNOSTICS.md 放在仓库根目录的原因:让每个普通用户都能成为高效的"现场工程师"。


