RetroArch 缩略图不显示？沿 3 条故障线一次修好-育师

RetroArch 缩略图不显示？沿 3 条故障线一次修好

【免费下载链接】RetroArchCross-platform, sophisticated frontend for the libretro API. Licensed GPLv3.项目地址: https://gitcode.com/GitHub_Trending/re/RetroArch

你打开 RetroArch，ROM 列表是一整排灰色占位方块，或是升级后菜单缩略图栏空空、History 里 Load Content 启动的游戏全无图。写给会操作菜单、没研究过缩略图缓存机制的中级用户：沿路径匹配、缓存残留、下载链路三条故障线逐一排查，用四段式工作流把图找回来。

症状速查：先定位你的 RetroArch 缩略图卡在哪一环

🔍

你看到的现象	最可能的原因	跳到哪一节
整个 playlist 都是占位块，只有零星几张有图	路径匹配断裂：图片名没命中 ROM / 数据库 / 短名三级中的任何一级	根因拆解，线一
删过存档后，部分缩略图陆续变灰	缓存残留条目仍指向已删除的图片	清理环节
升级前正常，升级后集体消失	旧版下载器被移除，新的下载源没接上	重建环节
Ozone 缩略图栏整个缺失，或全屏浏览时闪烁	Ozone 菜单驱动缺陷（1.17.0 已修复）	特殊场景
手机上显示正常，PC 端是灰块	目录权限或路径大小写敏感差异	特殊场景

如果表里没有你的情况，别纠结分析，直接往下走四段式工作流，从"确认"开始走是最快的路。

根因拆解：RetroArch 缩略图加载失败的三条链路

🔧

线一：路径匹配断裂

RetroArch 菜单查缩略图的顺序是固定的：先按 ROM 文件名找，找不到再按内容数据库里登记的名称找，最后落到游戏短名。这套"灵活匹配"三级链路在 1.17.0 才完整落地（CHANGES.md）。图片文件名只要三级都不命中，菜单就直接判定"无图"，不会追问第二句。还有一条隐性规则：走"加载内容"进来的游戏不进 playlist，拿不到数据库名，它的 History 缩略图此前一直是空的（1.17.0 修复，CHANGES.md）。

线二：缓存脏数据

缩略图缓存与 playlist 索引同时生成，但旧版本的清理逻辑并不对称：存档被垃圾回收时，对应缩略图可能留下来（最新开发版已同步处理，CHANGES.md）。缓存里的旧条目指向已删除的图片，而菜单信缓存、不重查——你看到的就是"永远不刷新的灰块"。

线三：下载链路调整

1.17.0 起，legacy 缩略图包下载器被整体移除（CHANGES.md）。之前依赖"自动下载整个缩略图包"的用户，升级后这条来源就断了，图自然补不上。新版改由按需下载接棒，它由独立开关控制，官方文案写得很直白：性能影响很大（设置定义文件）。至于无效下载请求在磁盘上建空目录的毛病，1.16.0 已经拦下（CHANGES.md）。

确认→清理→重建→验证：RetroArch 缩略图目录诊断与修复工作流

📂 确认：先钉死"卡在哪"

打开 RetroArch 用户目录（Windows 在 %APPDATA%\RetroArch，Linux/macOS 在 ~/.config/retroarch），检查 thumbnails 子目录是否长得像这样：

thumbnails/ └── [系统名]/ ├── Named_Boxarts/ ├── Named_Snaps/ └── Named_Titles/

这就是 RetroArch 缩略图目录的标准布局。九成"缩略图不显示"其实是"图根本没放进来"：对应系统目录如果是空的，那不是 bug，是资源问题。再顺手打开菜单确认显示位置，以 Ozone 主菜单为例：

版本在 1.16.0.2 及以上的话，还有一个按 playlist ROM 文件名找图的选项（CHANGES.md），先打开它，命名不规范的图也能在 ROM 名这一级命中。

清理：把旧缓存清掉

确认完路径，下一个高频坑就是残留条目。删缓存前先把 RetroArch 关掉，然后只清缩略图缓存层：

rm -rf ~/.config/retroarch/thumbnails

Windows: del /f /s /q %APPDATA%\RetroArch\thumbnails

为什么只清缓存、不动整个 thumbnails 目录：你手工放的盒绘就存在 thumbnails/[系统名]/ 下，全删等于把本地资源清零再重新下载。清缓存起作用的原理是，菜单下次启动时不会再命中旧条目，而是重新跑一遍三级路径匹配。

⚠️ 清完缓存后如果还是"一部分游戏有图、一部分没有"，就别再碰缓存了——这是命名问题，回到线一对文件名。

重建：把图补回来

两条路。路线 A 走本地：把对应系统的盒绘放进 thumbnails/[系统名]/Named_Boxarts/，重启程序。图片文件名命中 ROM 名、数据库名、短名任意一级即可；最新开发版起，除 png 外也支持 jpg/bmp/tga（CHANGES.md）。路线 B 走在线：浏览 playlist 触发按需下载，注意这个开关只补缺的、且拖性能，适合批量补图，补完随手关掉，别常开。

重建本质上是"在新缓存下重新匹配"。如果重建后仍不显示，结论很明确：文件名没命中任何一级，这不是多清几次缓存能解决的。

验证：看三个地方

别只看 playlist 就收工。依次看三处：playlist 视图（主展示面）、History（Load Content 内容的历史薄弱点）、快捷菜单的缩略图栏。原因是三个视图读的来源不同——playlist 有图而 History 没有，说明问题在路径而非图片资源，不用再回头清缓存。

配置速查：RetroArch 缓存清理与下载源相关的开关

On-Demand Thumbnail Downloads（设置 > 网络 > 按需缩略图）：默认关闭。只在想边浏览边补图时打开，补完即关，官方描述是"性能影响很大"。
缩略图类型轮换：右键摇杆可在 playlist 里循环 Boxart/Snap/Title。换类型能对照出缺的是哪一类，把问题从"全部没图"缩小到"某一类资源没图"。
Common Thumbnail Background（1.17.0 起，CHANGES.md）：统一空图占位底色，让你肉眼区分"没图"和"加载失败"。
Ozone 缩略图栏：旧版栏缺失与全屏闪烁的问题 1.17.0 已修复（CHANGES.md）。还在旧版的，升级，或临时换 XMB 菜单验证现象。
第三方工具：libretro-thumbnails 社区仓库是缩略图包的主来源，一个系统一个目录；Skraper 是批量媒体抓取器，适合给自制 ROM 批量命名配图。