RetroArch命令行完全指南：从入门到高级配置

最新推荐文章于 2025-12-14 06:02:27 发布
原创 最新推荐文章于 2025-12-14 06:02:27 发布 · 933 阅读 ·
CC 4.0 BY-SA版权
版权声明：本文为博主原创文章，遵循 CC 4.0 BY-SA 版权协议，转载请附上原文出处链接和本声明。

RetroArch命令行完全指南：从入门到高级配置

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

引言：为什么命令行是 RetroArch 的终极控制方式

你是否曾在图形界面中迷失于层层菜单？是否需要自动化游戏流程或远程控制 RetroArch？命令行界面（Command-Line Interface，CLI）是解锁 RetroArch 全部潜力的关键。本文将系统梳理 RetroArch 的 50+ 命令行参数，通过 20+ 实战示例和 5 个场景化配置方案，帮助你从入门到精通，让这款多平台模拟器前端真正为你所用。

读完本文后，你将能够：

  • 熟练使用 90% 的 RetroArch 命令行参数
  • 构建自动化游戏启动脚本
  • 配置高级视频录制与流式传输
  • 解决常见的命令行参数冲突问题
  • 掌握网络对战与远程控制技巧

基础入门： RetroArch 命令行语法与环境准备

核心语法结构

RetroArch 命令行遵循以下基本格式：

retroarch [ROM文件路径] [选项]...

关键规则：

  • ROM 文件路径必须位于选项之前
  • 选项区分大小写（例如 --Fullscreen 无效，必须小写 --fullscreen）
  • 短选项使用单连字符（-f），长选项使用双连字符（--fullscreen）
  • 多个短选项可合并（-fv 等效于 -f -v）

环境变量配置

RetroArch 支持多个环境变量用于路径配置，优先级高于配置文件：

环境变量作用配置文件等效项
LIBRETRO_DIRECTORY核心文件目录libretro_directory
LIBRETRO_ASSETS_DIRECTORY资源文件目录assets_directory
LIBRETRO_AUTOCONFIG_DIRECTORY控制器配置目录joypad_autoconfig_dir
LIBRETRO_CHEATS_DIRECTORY作弊码文件目录cheat_database_path
LIBRETRO_DATABASE_DIRECTORY数据库文件目录content_database_path
LIBRETRO_SYSTEM_DIRECTORY系统文件（BIOS）目录system_directory
LIBRETRO_VIDEO_FILTER_DIRECTORY视频滤镜目录video_filter_dir
LIBRETRO_VIDEO_SHADER_DIRECTORY着色器目录video_shader_dir

设置示例（Linux/macOS）：

export LIBRETRO_DIRECTORY="$HOME/retroarch/cores"
export LIBRETRO_SYSTEM_DIRECTORY="$HOME/retroarch/bios"
retroarch --menu

基础诊断命令

命令作用输出示例
retroarch --version显示版本信息RetroArch 1.16.0 (Git 9f2d3c1)
retroarch -V版本信息简写（1.16.0+）同上
retroarch --features显示编译特性Features: 64bit, OpenGL, Vulkan, ALSA...
retroarch --help显示基本帮助参数列表简要说明

版本兼容性提示：-V 选项自 1.16.0 版本起可用，旧版本请使用 --version --verbose 获取版本信息。

核心功能参数详解

内容加载与核心管理

基本内容加载
# 直接加载 ROM（自动选择关联核心）
retroarch ~/roms/nes/super_mario.nes

# 指定核心加载 ROM
retroarch ~/roms/psx/ff7.bin -L ~/cores/pcsx_rearmed_libretro.so

# 加载多个文件（用于多碟游戏）
retroarch "~roms/psx/ff7_disc1.bin" "~roms/psx/ff7_disc2.bin" -L ~/cores/pcsx_rearmed_libretro.so
子系统支持

部分核心支持子系统（如 MAME 机种）：

# 使用特定子系统加载内容
retroarch --subsystem "arcade" ~/roms/mame/pacman.zip -L ~/cores/mame_libretro.so
补丁应用

RetroArch 支持多种 ROM 补丁格式：

参数作用自动搜索
--ups PATCH应用 UPS 补丁同目录下 .ups 文件
--bps PATCH应用 BPS 补丁同目录下 .bps 文件
--ips PATCH应用 IPS 补丁同目录下 .ips 文件
--xdelta PATCH应用 Xdelta 补丁同目录下 .xdelta 文件
--no-patch禁用自动补丁-

示例：

# 手动指定补丁文件
retroarch ~/roms/snes/zelda.smc --ups ~/hacks/zelda_randomizer.ups -L ~/cores/snes9x_libretro.so

# 禁用自动补丁检测
retroarch ~/roms/nes/smb.nes --no-patch

配置文件管理

RetroArch 的配置系统支持多层级覆盖，优先级从高到低为：命令行参数 > 附加配置 > 主配置文件 > 默认配置。

基本配置加载
# 使用指定配置文件
retroarch --config ~/.config/retroarch/retroarch_custom.cfg

# 附加配置文件（覆盖主配置中的特定项）
retroarch --config ~/.config/retroarch/retroarch.cfg --appendconfig ~/.config/retroarch/overrides/nes.cfg,~/pergame/smb3.cfg

配置合并规则：--appendconfig 可指定多个文件（逗号分隔），后加载的文件会覆盖前面文件的相同配置项。

配置文件生成与维护
# 生成默认配置文件（仅在缺失时）
retroarch --menu

# 强制生成新配置（会覆盖现有文件）
retroarch --config /dev/null --menu

注意：当 config_save_on_exit = true 时，RetroArch 会在退出时覆盖配置文件，可能导致注释丢失。建议使用 --appendconfig 管理自定义设置。

视频与显示控制

显示模式控制
# 全屏模式
retroarch ~/roms/nes/smb.nes -f

# 窗口模式指定尺寸
retroarch ~/roms/nes/smb.nes --width 800 --height 600

# 强制分辨率（覆盖配置）
retroarch ~/roms/nes/smb.nes --video-fullscreen-x 1920 --video-fullscreen-y 1080
着色器控制
# 设置着色器预设
retroarch ~/roms/nes/smb.nes --set-shader ~/shaders/nes/ntsc.slangp

# 禁用着色器（覆盖自动预设）
retroarch ~/roms/nes/smb.nes --set-shader none

版本提示：--set-shader 选项自 1.14.0 版本起可用，用于覆盖游戏自动应用的着色器预设。

音频与输入控制

音频输出控制
# 禁用音频
retroarch ~/roms/nes/smb.nes --no-audio

# 指定音频设备
retroarch ~/roms/nes/smb.nes --audio-device "alsa_output.pci-0000_00_1f.3.analog-stereo"
输入设备配置
# 禁用端口 2 的输入设备
retroarch ~/roms/nes/smb.nes --nodevice 2

# 配置端口 1 为双模拟摇杆控制器
retroarch ~/roms/psx/ctrinity.bin --dualanalog 1 -L ~/cores/pcsx_rearmed_libretro.so

设备 ID 参考：不同核心可能使用不同的设备 ID，可通过 --verbose 日志查看支持的设备类型。

高级功能与场景配置

录制与流式传输

视频录制
# 基本录制（MKV格式，H.264/FLAC编码）
retroarch ~/roms/nes/smb.nes --record ~/videos/smb_playthrough.mkv

# 指定录制尺寸
retroarch ~/roms/nes/smb.nes --record ~/videos/smb_playthrough.mkv --size 1280x960

# 使用录制专用配置
retroarch ~/roms/nes/smb.nes --record ~/videos/smb_playthrough.mkv --recordconfig ~/configs/recording.cfg

录制配置优化：推荐在录制配置中设置 video_frame_delay = 3 以减少丢帧。

回放录制
# 播放 .replay 格式录像
retroarch --play-replay ~/replays/smb_speedrun.replay -L ~/cores/nes_libretro.so

# 录制新的回放
retroarch ~/roms/nes/smb.nes --record-replay ~/replays/new_run.replay -L ~/cores/nes_libretro.so

回放兼容性：回放文件与核心版本强关联，不同核心版本可能无法兼容。

网络对战（Netplay）

作为主机
# 启动主机（默认端口 55435）
retroarch ~/roms/nes/smb3.nes -L ~/cores/nes_libretro.so --host --nick "Player1"

# 指定端口和延迟帧
retroarch ~/roms/nes/smb3.nes -L ~/cores/nes_libretro.so --host --port 55436 --frames 3 --nick "HostPlayer"
作为客户端
# 连接到主机
retroarch --connect 192.168.1.100 -L ~/cores/nes_libretro.so --nick "Player2"

#  spectator 模式（仅观看）
retroarch --connect 192.168.1.100 --spectate -L ~/cores/nes_libretro.so

网络优化建议：

  • 局域网推荐 --frames 0（无延迟同步）
  • 互联网对战建议 --frames 3-5（根据延迟调整）
  • 使用有线网络连接以减少丢包

远程控制与自动化

发送命令到运行中的实例
# 暂停当前游戏
retroarch --command "pause;localhost;5535"

# 加载状态槽 1
retroarch --command "load_state 1;192.168.1.100;5535"

支持的命令：pause、resume、load_state [slot]、save_state [slot]、quit 等，使用 --command "invalid" 获取完整列表。

批量内容扫描
# 手动扫描目录并生成播放列表
retroarch --menu --verbose --manual-scan ~/roms/nes/ "Nintendo Entertainment System" ~/cores/nes_libretro.so "NES"

扫描参数说明：

  1. 目标目录
  2. 系统名称（显示用）
  3. 核心路径
  4. 数据库简写（用于匹配数据库）

调试与故障排除

高级日志控制
# 详细日志输出到文件
retroarch ~/roms/nes/smb.nes --verbose --log-file ~/logs/retroarch_debug.log

# 仅记录错误信息
retroarch ~/roms/nes/smb.nes --log-level 0 --log-file ~/logs/retroarch_errors.log

日志级别：0=错误，1=警告，2=信息，3=调试（默认）

错误恢复配置
# 错误时自动加载菜单
retroarch ~/roms/unknown_game.bin -L ~/cores/nes_libretro.so --load-menu-on-error

# 禁用特定模块以诊断问题
retroarch --menu --disable-ffmpeg --disable-netplay

高级参数速查表

按功能分类的参数参考

配置与启动
参数描述版本要求
--menu启动菜单模式所有版本
--config PATH指定主配置文件所有版本
--appendconfig PATH附加配置文件1.7.0+
--no-config不加载配置文件所有版本
--load-menu-on-error错误时加载菜单1.9.0+
内容与核心
参数描述版本要求
-L PATH指定核心库路径所有版本
--subsystem NAME使用核心子系统1.7.0+
--entryslot NUM指定起始存档槽1.9.0+
--ups PATCH应用 UPS 补丁所有版本
--bps PATCH应用 BPS 补丁1.7.0+
显示与输出
参数描述版本要求
-f/--fullscreen全屏模式所有版本
--width W窗口宽度所有版本
--height H窗口高度所有版本
--set-shader PATH设置着色器1.14.0+
--size WxH录制分辨率所有版本
录制与网络
参数描述版本要求
--record PATH录制视频所有版本
--record-replay PATH录制回放所有版本
--play-replay PATH播放回放所有版本
--host网络对战主机所有版本
--connect HOST连接对战主机所有版本
--spectate观战模式1.7.0+
高级控制
参数描述版本要求
--command CMD发送命令到运行实例1.8.0+
--log-file PATH日志输出到文件1.9.0+
--verbose/-v详细日志所有版本
--features显示编译特性所有版本
--detach后台运行（Windows）所有版本

参数冲突与优先级规则

  1. 命令行参数 > 配置文件：所有命令行参数会覆盖配置文件中的对应设置
  2. 特定参数 > 通用参数：例如 --width 和 --height 会覆盖 --size 中的尺寸设置
  3. 后出现参数 > 先出现参数：同类型参数后出现的会覆盖前面的设置

冲突示例：

# --fullscreen 会覆盖窗口尺寸设置
retroarch ~/roms/nes/smb.nes --width 800 --height 600 -f

实战案例：5 个实用脚本与配置

1. 一键启动带自动录像的游戏

#!/bin/bash
# 文件名: retro_record.sh
# 用法: ./retro_record.sh <rom_path> <core_path> <output_name>

ROM="$1"
CORE="$2"
NAME="$3"
DATE=$(date +%Y%m%d_%H%M%S)
OUTPUT_DIR="$HOME/videos/retroarch"
LOG_DIR="$HOME/logs/retroarch"

# 创建目录
mkdir -p "$OUTPUT_DIR" "$LOG_DIR"

# 启动游戏并录制
retroarch "$ROM" -L "$CORE" \
  --record "$OUTPUT_DIR/${NAME}_${DATE}.mkv" \
  --size 1280x960 \
  --verbose \
  --log-file "$LOG_DIR/${NAME}_${DATE}.log"

echo "录制完成: $OUTPUT_DIR/${NAME}_${DATE}.mkv"

2. 网络对战主机快速启动器

#!/bin/bash
# 文件名: retro_host.sh
# 用法: ./retro_host.sh <rom_path> <core_path> <port> <nick>

ROM="$1"
CORE="$2"
PORT="${3:-55435}"
NICK="${4:-RetroHost}"
FRAMES="${5:-3}"

retroarch "$ROM" -L "$CORE" \
  --host \
  --port "$PORT" \
  --nick "$NICK" \
  --frames "$FRAMES" \
  --verbose \
  --log-file "$HOME/logs/netplay_host_$(date +%Y%m%d).log"

3. 多配置文件管理方案

# 基础配置 + 性能优化 + 游戏特定配置
retroarch ~/roms/psx/ff7.bin \
  -L ~/cores/pcsx_rearmed_libretro.so \
  --config ~/.config/retroarch/base.cfg \
  --appendconfig ~/.config/retroarch/performance.cfg,~/roms/psx/ff7.cfg

4. 自动生成带缩略图的游戏列表

#!/bin/bash
# 文件名: generate_playlist.sh
# 用法: ./generate_playlist.sh <system_name> <rom_dir> <core_path> <db_shortname>

SYSTEM="$1"
ROM_DIR="$2"
CORE="$3"
DB="$4"
PLAYLIST_DIR="$HOME/.config/retroarch/playlists"
PLAYLIST_FILE="${PLAYLIST_DIR}/${SYSTEM}.lpl"

# 创建播放列表目录
mkdir -p "$PLAYLIST_DIR"

# 执行扫描并生成播放列表
retroarch --menu --verbose \
  --manual-scan "$ROM_DIR" "$SYSTEM" "$CORE" "$DB" \
  --log-file "$HOME/logs/playlist_scan_${SYSTEM}.log"

echo "播放列表已生成: $PLAYLIST_FILE"
echo "缩略图下载可能需要在菜单中手动触发"

5. 低性能设备优化启动脚本

#!/bin/bash
# 文件名: retro_light.sh
# 适用于树莓派等低性能设备

retroarch "$1" -L "$2" \
  --config ~/.config/retroarch/lightweight.cfg \
  --disable-ffmpeg \
  --disable-netplay \
  --disable-screenshot \
  --video-smooth=false \
  --audio-latency=64 \
  --verbose

总结与进阶学习路径

RetroArch 命令行界面提供了图形界面无法比拟的灵活性和控制力。通过本文介绍的参数和场景配置，你可以构建从简单启动到复杂自动化的完整工作流。

进阶学习资源

  1. 官方文档：深入理解可参考 docs/retroarch.6 手册页
  2. 源代码研究：命令行处理逻辑位于 retroarch.c 中的 parse_command_line 函数
  3. 社区资源：Libretro 论坛和 GitHub 讨论区有大量高级使用技巧

下一步建议

  1. 为常用游戏创建个性化启动脚本
  2. 探索 --appendconfig 实现多场景配置切换
  3. 尝试结合 cron 或系统服务实现定时录制/直播
  4. 研究网络命令协议，开发自定义远程控制工具

掌握 RetroArch 命令行不仅能提升你的游戏体验，更能培养你在类 Unix 环境下的命令行操作能力——这是技术领域的核心竞争力之一。现在就拿起你的手柄，用命令行启动游戏，体验这种高效控制方式的魅力吧！

如果你觉得本文对你有帮助，请点赞、收藏并关注以获取更多 RetroArch 高级教程。下期我们将探讨高级着色器配置与性能优化技巧，敬请期待！

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

创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考

实付元
使用余额支付
点击重新获取
扫码支付
钱包余额 0

抵扣说明：

1.余额是钱包充值的虚拟货币，按照1:1的比例进行支付金额的抵扣。
2.余额无法直接购买下载，可以购买VIP、付费专栏及课程。

余额充值