RetroPie-Setup网络刮削器使用指南：自动获取游戏封面与介绍
项目地址: https://gitcode.com/gh_mirrors/re/RetroPie-Setup RetroPie-Setup网络刮削器（Scraper）是RetroPie系统中用于自动获取游戏封面、介绍、视频等媒体资源的工具，通过scriptmodules/supplementary/scraper.sh脚本实现核心功能。它能帮助玩家快速美化游戏库，无需手动添加资源。本文将详细介绍其安装、配置和使用方法，解决刮削过程中常见的资源缺失、配置复杂等问题。
刮削器工作原理与核心组件
基本工作流程
刮削器通过分析ROM文件的元数据（如文件名、哈希值），从预设的网络数据库（如OpenVGDB、theGamesDB）获取匹配的媒体资源，并生成EmulationStation可识别的gamelist.xml文件。资源存储路径可配置为ROM目录内或系统统一目录，具体逻辑在scraper.sh第69-77行定义。
核心配置文件
刮削器的所有参数通过配置文件configdir/all/scraper.cfg管理，包括数据源选择、图片尺寸、资源类型等。配置加载逻辑由scraper.sh第194行的_load_config_scraper函数实现，默认配置如下：
use_thumbs = 1 # 是否仅下载缩略图
screenshots = 0 # 是否优先截图资源
max_width = 400 # 图片最大宽度
console_src = 1 # 控制台游戏数据源（1=theGamesDB）
mame_src = 2 # 街机游戏数据源（2=ArcadeItalia）
安装与环境准备
自动安装流程
RetroPie-Setup已集成刮削器安装脚本，通过以下步骤完成安装：
- 进入RetroPie-Setup菜单，选择"Manage Packages"
- 选择"Optional Packages" → "scraper"
- 选择"Install from source"
安装过程会自动处理依赖项（如Golang环境），并编译二进制文件，相关逻辑在scraper.sh第23-41行中定义。安装完成后，可执行文件位于/home/pi/RetroPie-Setup/scriptmodules/supplementary/scraper/目录。
手动安装验证
若自动安装失败，可通过以下命令手动验证安装状态：
# 检查刮削器版本
/home/pi/RetroPie-Setup/scriptmodules/supplementary/scraper/scraper -version
成功安装会显示版本信息，如scraper v1.4.2。
图形界面配置详解
启动刮削器配置界面
在RetroPie-Setup主菜单选择"Supplementary" → "scraper"即可进入图形配置界面。注意：启动前需确保EmulationStation已关闭，否则会提示"数据将被覆盖"的警告，如scraper.sh第196-199行所示。
关键配置项说明
配置界面提供12项可调整参数，以下是核心选项的优化建议：
| 配置项 | 作用 | 推荐设置 |
|---|---|---|
| 3. Thumbnails only | 仅下载小尺寸封面 | 开启（节省空间） |
| 4. Prefer screenshots | 优先获取游戏截图 | 关闭（封面更美观） |
| 6. Console Source | 控制台游戏数据源 | OpenVGDB（0） |
| V. Download Videos | 下载游戏视频预览 | 关闭（占用带宽） |
| W/H. Max image size | 图片尺寸限制 | 640x480（平衡画质与性能） |
配置修改会实时保存到scraper.cfg，通过scraper.sh第296-340行的iniSet调用实现参数持久化。
刮削操作实战指南
选择刮削范围
刮削器支持三种范围选择，通过主界面的1-2选项切换：
全系统刮削
选择"1. Scrape all systems"会自动扫描所有包含ROM的目录，批量处理所有游戏。扫描逻辑由scraper.sh第55行的list_systems_scraper函数实现，通过查找/home/pi/RetroPie/roms/下的非空目录完成系统识别。
自定义系统刮削
选择"2. Scrape chosen systems"可打开系统选择界面，通过空格勾选需要刮削的平台（如nes、mame）。多选逻辑在scraper.sh第152-177行实现，适合分批次更新资源。
刮削过程监控
刮削开始后，终端会显示实时进度，包括：
- 当前处理的游戏系统（如"nes"）
- 已完成数量/总数量（如"Processed 23/56 ROMs"）
- 资源下载状态（如"Downloaded boxart for Super Mario Bros"）
若需中断刮削，可按Ctrl+C终止进程，已下载的资源不会丢失，下次可选择"Gamelist (Append)"模式继续。
高级配置与优化
数据源切换策略
刮削器支持多数据源切换，以应对不同地区的网络状况：
| 数据源类型 | 适用场景 | 配置值 |
|---|---|---|
| theGamesDB | 全球稳定，资源丰富 | console_src=1 |
| OpenVGDB | 离线支持，本地数据库 | console_src=0 |
| ScreenScraper | 多语言支持，含视频 | console_src=2 |
切换方法：在刮削器配置界面选择"6. Console Source"循环切换，配置会实时写入scraper.cfg。
资源存储路径调整
默认情况下，刮削资源存储在系统目录~/.emulationstation/downloaded_images/，通过scraper.sh第74-75行定义。若需将资源与ROM文件放在同一目录（便于备份），可开启"9. Use rom folder for gamelist & images"选项，此时资源会保存至/home/pi/RetroPie/roms/<系统名>/images/。
图片尺寸优化
对于性能较弱的设备（如Raspberry Pi Zero），建议将图片尺寸调整为320x240以减少加载延迟：
- 在配置界面选择"W. Max image width"
- 输入"320"并确认
- 同样设置"H. Max image height"为"240"
修改后新下载的图片会自动压缩，配置保存在scraper.cfg的max_width和max_height字段。
常见问题解决方案
刮削进度停滞
若刮削过程卡在某个游戏，通常是由于网络超时或ROM文件名异常：
- 检查网络连接，建议使用有线网络
- 重命名异常ROM文件（去除特殊字符、简化名称）
- 手动跳过该游戏：按Ctrl+C终止，启用"Append"模式后重新刮削
中文游戏乱码
若游戏标题出现乱码，需修改EmulationStation字体设置：
- 进入RetroPie-Setup → "Configuration / Tools" → "emulationstation"
- 选择"Change Emulation Station Font"
- 选择支持中文的字体（如"WenQuanYi Micro Hei"）
资源重复下载
若同一游戏多次刮削导致资源重复，可开启"8. Gamelist (Append)"模式，此时刮削器会跳过已存在的游戏条目，仅处理新增ROM。
故障排除与日志分析
日志文件位置
刮削器运行日志默认输出到终端，关键操作记录可通过以下命令查看：
tail -f /home/pi/RetroPie-Setup/logs/rps_*.log | grep scraper
常见错误代码
| 错误信息 | 原因分析 | 解决方案 |
|---|---|---|
| "no systems found" | ROM目录为空 | 确认ROM文件已放入正确目录 |
| "API rate limit exceeded" | 数据源请求超限 | 等待1小时后重试或切换数据源 |
| "image download failed" | 网络不稳定 | 检查DNS设置或使用代理 |
总结与最佳实践
推荐工作流
- 初始刮削：安装系统后立即进行全系统刮削，使用默认配置
- 增量更新：新增游戏后使用"Scrape chosen systems" + "Append"模式
- 定期维护：每季度切换数据源进行完整刮削，更新资源
资源管理建议
- 定期备份
gamelist.xml和images目录，防止意外丢失 - 对于稀缺游戏资源，手动补充后禁用对应系统的刮削
- 使用工具skyscraper（高级刮削器）处理复杂场景
通过合理配置和使用刮削器，可在10分钟内完成500+游戏的资源美化，大幅提升RetroPie系统的使用体验。更多高级功能可参考官方文档scriptmodules/supplementary/scraper.sh的源码注释。
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
