RetroArch 缩略图加载失败：按症状排查修复
【免费下载链接】RetroArchCross-platform, sophisticated frontend for the libretro API. Licensed GPLv3.项目地址: https://gitcode.com/GitHub_Trending/re/RetroArch
RetroArch 缩略图不显示、游戏列表一片黑色占位符——按你看到的症状走下面的分支，3 分钟内定位原因。
先对照——你现在看到的是哪种？
| 症状 | 一句话特征 | 跳转 |
|---|---|---|
| 列表里黑色占位 / 破损图标 | 图片文件名和库里名字哪个都对不上 | 黑色占位：匹配失败 |
| 升级后不再自动下图 | 老版本有图，升到 1.17.0 后没了 | 缩略图不自动下载 |
| Ozone 菜单缩略图缺失或闪屏 | 只有这一个界面异常 | Ozone 缩略图缺失或闪烁 |
花 1 分钟排除低级问题
- 图片放在用户配置目录下的
thumbnails/（Linux 默认~/.config/retroarch/thumbnails/），不是安装目录 - 版本低于 1.18.0 的构建只认 png，jpg/bmp/tga 是 1.18.0 才支持的
- 在 1.16.0 之前的版本上跑？匹配规则在后续版本改过，老版本行为不同
- PC 用户确认当前账户对缩略图目录有读取权限——一半的"玄学问题"是这个 😄
按症状深入修
黑色占位：匹配失败
为什么：RetroArch 找图的顺序是——先按 playlist 条目里的标题名，再按内容数据库（把游戏名和 ROM 文件对应起来的清单文件）里的标准名，最后退到短名称，这叫"灵活匹配"（见 CHANGES.md 1.17.0 段）。你一旦改过 ROM 名或 playlist 条目名，三把钥匙全对不上，旧图就永远找不到。1.16.0.2 又补了一个"按 playlist ROM 文件名找图"的选项，老版本根本没有。
怎么改：
- 确认图片在
thumbnails/[系统名]/Named_Boxarts（或 Named_Snaps、Named_Titles）里，系统名形如Nintendo - Nintendo Entertainment System - 把图片文件名改成和 ROM 文件名一致（不含扩展名），不行再换成数据库里的标准名
- 在菜单里打开"按 playlist ROM 文件名查找缩略图"的开关（以你当前版本实际菜单为准）
改完看什么：刷新 playlist，黑色占位逐格变成盒绘。
缩略图不自动下载
为什么：1.17.0 移除了 legacy 缩略图包下载器（CHANGES.md 1.17.0 段），旧版"进菜单顺手把缺的图拉下来"的通道没有了。说人话就是功能被砍了，不是网络故障，重拨宽带也没用。
怎么改：
- 自行获取对应系统的图片包（内含 Named_Boxarts 等子目录）
- 放进用户配置目录的
thumbnails/，文件夹名和系统名一致 - 不想手动摆？走菜单里的内容下载入口（以你当前版本实际菜单为准）
改完看什么：进对应 playlist，缺图条目在网络加载约 1~2 秒后显示出画面。
Ozone 缩略图缺失或闪烁
为什么：Ozone 的缩略图栏曾有"栏缺失、全屏浏览闪烁、侧边栏焦点错位"一串 bug，1.17.0 才集中修掉（CHANGES.md 1.17.0 段 MENU/OZONE 条目）。停在 1.16.x 上遇到它属于正常现象。
怎么改：
- 升级到 1.17.0 及以上，无需改任何设置
- 暂时不能升级？把界面换成 RGUI（设置 > 用户界面 > 菜单驱动）再看——图正常就是渲染问题，图还是没有就是图片本身的问题
改完看什么：缩略图栏常驻可见，全屏浏览时不再闪白屏或缺角。
三条习惯，少踩这个坑
- 摆放图片包就按"系统名 / Named_Boxarts"两级结构来，别整成一个大杂烩文件夹
- 给游戏改名时，把对应的缩略图文件一起改名，保持名字始终一致
- 动手排查前先翻 CHANGES.md 确认当前版本是否已修复，省掉一半弯路
还解决不了？
- 到项目官方仓库开 Issue，提交时带上菜单日志：先在 设置 > 日志记录 里开启文件日志（以你当前版本实际菜单为准），复现一次问题，把
config/log下生成的日志文件附在 Issue 里 - 或把 playlist 截图、缩略图目录的
tree输出发到项目社区频道，让维护者帮你对照
【免费下载链接】RetroArchCross-platform, sophisticated frontend for the libretro API. Licensed GPLv3.项目地址: https://gitcode.com/GitHub_Trending/re/RetroArch
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
