MAKO 不工作?终极排障清单与私有诊断报告生成全流程

原创2026-11-03 09:18:42534 阅读

MAKO 不工作?终极排障清单与私有诊断报告生成全流程

MAKO 是 Linux 游戏平台上的新一代 Vulkan 图形层,为 Steam Deck、Steam Machine 和桌面 Linux 带来 Lossless Scaling 帧生成、超分辨率缩放与着色器增强。当 MAKO 不工作时,不必盲目重装——本文提供一份按优先级排列的排障清单,并手把手教你走完"开启日志 → 复现问题 → 生成报告 → 私有提交"的诊断报告生成全流程,把问题一次性交给开发者。

MAKO Linux Vulkan 图形层排障指南横幅

排障前先自查: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/。

MAKO 帧生成功能效果演示画面

私有诊断报告生成全流程: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 步:复现一次问题

启动游戏,完整复现一次异常现象(卡住、掉帧、画面错误均可),记下表现,然后彻底退出游戏。⚠️ 退出前先完成复现,且在开始下一次测试前就收集报告,否则日志会话会被覆盖。

MAKO 渲染层故障排查流程示意画面

第 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 步:私有提交报告

  1. 打开 MAKO-diagnostics.txt,手动删去个人敏感信息(路径、用户名等);
  2. 通过官方私有诊断表单提交(入口见上述两份 COLLECT_DIAGNOSTICS 文档),独立安装选 MAKO Renderer (standalone/direct installation),Decky 选 MAKO Decky (Decky Loader plugin),拿不准的选项一律选 Unknown;
  3. 🚫 两个红线:不要把日志公开贴到 issue 或论坛,不要附上 Lossless.dll。

对比测试的小技巧

排查画质或帧率回归时,每次改动后单独收集一份报告,并记录改了什么设置;尽量使用同一场景、同一游戏画质,HDR 相关对比还要记下游戏分辨率与显示器分辨率,开发者才能精准定位。

收尾:记住这个排障顺序

✅ 快速回忆路径:Vulkan 后端 → 启动参数 → 进程匹配 → 前置依赖(Lossless Scaling)→ 配置校验(mako-cli validate)→ 诊断报告(mako-diagnostics)。前四步解决大多数"不工作",最后两步把疑难杂症打包成专业报告交给团队——这正是 MAKO 项目把 COLLECT_DIAGNOSTICS.md 放在仓库根目录的原因:让每个普通用户都能成为高效的"现场工程师"。

登录后查看全文
MAKO