SSH连接Batocera教程-一起DIY吧

📖 本文由 Batocera 官方 Wiki 翻译整理，内容可能随版本更新而变化。

远程指挥中心：通过 SSH 或 Xterm 掌控系统

为了更方便地管理 Batocera，我们通常会从另一台电脑远程登录它的终端。比起直接在小小的屏幕上敲代码，这种方式支持命令历史记录和彩色显示，操作起来顺滑得多。

第一阶段：确认远程访问权限

在连接之前，我们需要确保 Batocera 的“大门”是敞开的。

第一步：核对配置文件
访问并打开 /userdata/system/Batocera.conf 文件。
第二步：激活 SSH 开关
检查文件中是否存在 system.SSH.enabled=1 这行代码。
第三步：解除屏蔽
确保这行代码开头没有 # 号。

生活化类比：这就像是在家里装了一个远程控制锁。默认情况下锁是装好的，我们只需要确认开关处于“开启”状态，外面的人（另一台电脑）才能凭钥匙进来。

第二阶段：建立连接（Windows、Mac 或 Linux）

Batocera 系统只有一个超级管理员账号：root。

对于 Windows 用户：
【提示】强烈建议下载并使用 PuTTY 或 KiTTY 这类专业的远程连接工具。
对于 Mac/Linux/Windows 10+ 用户：
直接打开自带的终端（Terminal）或命令提示符（CMD），输入：ssh root@Batocera.local 或 ssh root@Batocera。

第三阶段：寻找正确的“门牌号”

如果通过名称无法连接，我们需要使用更精准的 IP 地址（IP Address）。

第一步：查找地址
在 Batocera 游戏界面中，按下 主菜单（MAIN MENU） -> 网络设置（NETWORK SETTINGS）。
第二步：记录数值
找到类似 192.168.###.### 的一串数字。
第三步：手动连接
在你的 SSH 工具中输入 root@192.168.###.###（将 # 替换为实际数字）进行连接。

【注意】：首次连接时，系统可能会询问你是否信任该设备，输入 yes 并回车即可。默认密码通常为 linux。

PuTTY 配置参考图

如果你使用的是 PuTTY，配置界面应当如下图所示：

[此处为 PuTTY 配置示例图：主机名处填写 IP 地址，连接类型选择 SSH]

下一步行动

连接成功后，你就已经进入了 Batocera 的心脏。你可以开始输入各种指令来手动调试蓝牙、修改系统文件或管理你的游戏库了。

远程连接与安全进阶指南

当你配置好连接工具后，最后几个细节将决定你的操作是否顺手且安全。

第一阶段：登录与保存配置

为了以后不再重复输入繁琐的信息，我们可以把这次连接“固化”下来。

第一步：保存配置文件
在工具（如 PuTTY）中设置好所有参数后，点击“保存（Save）”。这样就会创建一个可以双击直接运行的配置文件，下次登录一秒进系统。
第二步：输入登录密码
在 SSH 会话窗口开启后，系统会提示你输入密码。默认密码是 linux。

【提示】：在 Linux 系统中输入密码时，屏幕上不会显示星号或任何字符。别担心，这不是键盘坏了，而是 Linux 的安全传统。你尽管闭着眼睛敲完并按回车（Enter）就行。

第二阶段：强化系统安全

默认情况下，Batocera 的门槛较低。如果你希望提高安全性，可以开启“强制安全（Enforce Security）”模式。

第一步：开启安全开关
在游戏界面进入 主菜单（MAIN MENU） > 系统设置（SYSTEM SETTINGS） > 安全（SECURITY）。
第二步：设置专属密码
开启“强制安全”选项，并设定一个你自己的密码。

生活化类比：这就像是把原本虚掩的房门锁上了。开启这个功能后，不仅 SSH 登录需要密码，连你在电脑上访问游戏机的网络共享文件夹（Network share）也必须输入账号密码。

【注意】：即便开启了安全增强，Batocera 依然不是一个绝对安全的操作系统。请务必不要将其暴露在公网（外网）中，由此带来的风险需自行承担。

第三阶段：本地终端访问

如果你不想使用另一台电脑，也可以直接在 Batocera 机器上操作。

操作方法：
按下 [F1] 进入文件管理器，从“应用程序（Applications）”菜单中打开 xterm 终端。

【注意】：本地终端（xterm）仅支持使用了 Xorg 后端（Xorg backend）的平台，例如常见的 x86_64（普通 PC）架构。

登录成功的标志

当你看到屏幕上出现由字符拼成的精美图案时，恭喜你，你已经成功“入侵”了自己的系统！

技术小贴士：这种用纯文字字符拼成的图形被称为 ASCII 艺术（ASCII art），它是极客圈里一种复古又浪漫的表达方式。

# 登录成功后的画面示例
                     __________
    _________       /          \
   /        /      /            \
  /________/      /______________\
  |        |      |              |
  | Batocera|      |    LINUX     |
  |________|      |______________|

终端交互技巧与安全预警

除了通过其他电脑远程连接，你还可以直接在 Batocera 机器上开启一个全新的“对话窗口”。

第一阶段：本地多会话切换

如果你手边没有第二台电脑，可以使用快捷键直接调出系统的控制台会话（TTY session）。

第一步：切入后台控制台
在 Batocera 的任何界面下，按下 [Ctrl]+[Alt]+[F5]。此时屏幕会变黑并提示登录，请输入账号 root 和密码 linux。
第二步：返回游戏界面
操作完成后，按下 [Ctrl]+[Alt]+[F2] 即可切回熟悉的游玩界面。

【注意】：在 Batocera v31 及更早版本中，返回键是 [Ctrl]+[Alt]+[F3]。此外，由于旧版本在本地终端下经常会出现文字输入乱码的问题，除非是万不得已的紧急情况，否则不建议在 v31 及以下版本使用本地控制台。

第二阶段：命令行“避坑”指南

当你踏入命令行的世界，一定要弄清楚每条指令背后的真正含义。

生活化类比：命令行就像是一个言听计从但“没脑子”的超级助手。如果你命令它“把这叠钱烧了”，它绝对不会问你为什么，而是直接划火柴。

隐形的清空操作：
比如指令 > empty.txt。这条命令会创建一个名为 empty.txt 的空文件。听起来没问题？但如果你当前目录下已经有一个同名且重要的文件，这条命令会瞬间抹除其所有内容，让它变成一张白纸。
毁灭性的“禁咒”：
有些极短的代码具有恐怖的破坏力。例如 rm -rf /（删除系统所有内容）或者被称为“叉子炸弹（Fork Bomb）”的奇怪符号组合 :(){:|:&};:。这些指令会在没有任何警告提示的情况下，直接彻底摧毁你的硬盘数据！

第三阶段：PuTTY 的特殊操作

如果你在 Windows 上使用 PuTTY 工具，请注意它的交互方式与普通办公软件大不相同。

【提示】复制与粘贴：
PuTTY 的复制和粘贴逻辑与大多数 Windows 程序都不一样。例如，通常选中文本即代表复制，右键点击即代表粘贴。如果你想深入了解这些进阶功能，请务必查阅 PuTTY 的官方文档。

第四阶段：免密登录（Password-less authentication）

如果你觉得每次输入密码太麻烦，可以配置免密验证（Password-less authentication）。这一部分涉及到通过密钥对实现自动身份识别，让你的远程连接更加高效。

实现免密登录：让远程连接更省心

通过配置，Batocera 可以“记住”你电脑的身份识别码，这样以后每次登录时，你就不再需要苦等密码框并手动输入那个枯燥的 linux 了。

第一阶段：前期准备与格式检查

【注意】：本教程仅适用于你的 Batocera 用户数据分区（userdata）格式为 Linux 原生格式（如默认的 ext4 或 btrfs）的情况。如果你的分区是 FAT32 或 NTFS，下文中的权限修改命令（chmod）将无法生效，从而导致免密设置失败。

生活化类比：这就像是在门锁上加装指纹识别。首先，你的门框（分区格式）必须是结实的木头或金属，如果门框是塑料（FAT32）做的，螺丝（权限设置）就拧不紧，指纹锁也就装不上。

第二阶段：在 Batocera 端铺设路径

我们需要先在游戏机系统里清理权限并准备好接收“指纹”的容器。

第一步：统一目录权限
在 Batocera 终端执行以下指令，确保系统文件夹的归属和读写权限完全正确：
bash chown root:root / /userdata/ /userdata/system/ chmod 755 / /userdata/ /userdata/system/
第二步：创建钥匙存放盒
依次输入以下指令，建立一个专门存放授权钥匙的隐藏文件夹和文件：
bash mkdir -p ~/.ssh touch ~/.ssh/authorized_keys
第三步：锁定安全权限
为了防止别人乱动你的钥匙，需要把盒子的权限锁死：
bash chmod 700 ~/.ssh chmod 600 ~/.ssh/authorized_keys

第三阶段：在你的电脑上生成并传送“钥匙”

现在，我们需要在常用的这台电脑（即客户端）上生成一对身份证明，并把其中的公钥（Public key）发送给 Batocera。

如果你使用的是 Linux 或 Mac 系统：

第一步：生成密钥对
在你的电脑终端输入：
bash ssh-keygen
【提示】：一路上疯狂按回车键（Enter）跳过所有问题即可。不用担心那个“主密码（Master password）”设置，直接留空更方便。
第二步：将“钥匙”寄送给 Batocera
运行以下这条复杂的长指令，将你电脑生成的公钥内容追加到 Batocera 的授权名单中：
bash cat ~/.ssh/id_rsa.pub | ssh root@batocera.local 'cat >> /userdata/system/.ssh/authorized_keys'

生活化类比：这就好比你生成了一张指纹贴纸（公钥），然后通过快递（这一长串命令）把它寄到了 Batocera 那里，并贴在了它的“熟人名单”里。下次你再来，它看一眼指纹就直接开门了。

温馨提示：在执行上述指令时，如果你的设备设置了固定 IP 地址（Static IP），请记得将命令中的 Batocera.local 替换为具体的 IP 数字。
如果你是 Windows 用户：
手动打开你电脑里的 C:<你的用户名>.ssh\id_rsa.pub 文件，复制其中的全部内容，然后粘贴到 Batocera 系统中的 ~/.ssh/authorized_keys 文件里即可。

大功告成！现在你通过客户端连接 Batocera 时，系统就会直接为你敞开大门，再也不用手动敲密码了。

【注意】：有些资深玩家可能想尝试使用 ssh-copy-id 指令来一键配置。请注意，这个方法在 Batocera 上是行不通的。这是因为 Batocera 采用了轻量级的 Dropbear 服务（Dropbear SSH service），它在架构上有一些特殊的限制。

进阶操作：从 Batocera 访问其他设备

除了让电脑控制游戏机，有时候我们也需要反过来：让 Batocera 自动登录到另一台远程机器上。

由于 Batocera 运行的是 Dropbear 服务，传统的 ssh-keygen 指令在这里会“罢工”。我们需要使用它专属的工具来生成“钥匙”。

第一步：生成专用密钥对
在 Batocera 终端输入以下指令：
bash dropbearkey -t rsa -f ~/.ssh/id_dropbear
执行完毕后，屏幕上会直接显示出你的公钥内容。
第二步：保存或提取公钥
如果你当时没来得及保存，或者之后想再次查看这把“钥匙”，请运行下面这条指令。它会把你的公钥提取出来并专门存放在一个文件中：
bash dropbearkey -y -f /userdata/system/.ssh/id_dropbear | grep '^ssh-rsa' > /userdata/system/.ssh/id_dropbear.pub

生活化类比：这就像是换了一家制锁公司。虽然传统的模具（ssh-keygen）不能用了，但我们找来了这家公司的专用机器（dropbearkey），照样能打出开启远程大门的钥匙。

跨设备互通与 SSH 基础指令指南

完成了密钥生成后，你就可以像之前介绍的那样，将生成的公钥复制到远程机器上，从而实现从 Batocera 自动登录其他设备的操作。

1. 认识 Batocera 的命令行环境

一旦成功通过 SSH 连接，你就进入了一个基于 Unix 的指令世界。

【提示】：虽然你可以使用大部分标准的 Unix 指令，但请记住，Batocera 是一个精简的“构建根（Build-root）”系统。为了保持轻量，它只包含了最核心的 GNU 核心工具集（GNU coreutils）。

生活化类比：这就像是一个“极简主义者的背包”。它里面只有生存必备的工具（如打火机、小刀），而没有像 Ubuntu 或 Mint 那样庞大而全能的“家庭工具箱”。所以，你在网上搜到的某些针对 Ubuntu 的复杂指令，在这里可能会提示“找不到命令”。

2. 学会使用“求助”功能

在命令行世界里，你不需要死记硬背每个参数。大多数工具都内置了说明书。

操作方法：
在命令后面加上 --help 选项。例如，输入 cp --help，系统就会打印出“文件复制（Copy）”指令的使用说明。

示例：cp 指令的帮助信息（基于 BusyBox 工具箱）

BusyBox v1.31.1 (2020-11-28 14:11:54 CET) multi-call binary.


用法: cp [选项] 源文件... 目标目录
功能：将源文件（SOURCE）复制到目标位置（DEST）

常用选项说明： -a 等同于 -dpR（保留所有属性并递归） -R, -r 递归复制（用于复制整个文件夹） -d, -P 保留符号链接（快捷方式） -p 如果可能，保留文件属性（如修改时间、权限） -f 强制覆盖已有文件 -i 覆盖前先询问你（更安全） -u 仅在源文件比目标文件更新时才进行复制

3. 操作建议

第一步：确认环境
输入命令前，先确认你当前处于哪个目录下（使用 pwd 指令）。
第二步：小规模测试
在使用像 cp（复制）或 mv（移动）这类涉及文件的指令时，可以先拿一个不重要的文件练手。
第三步：利用帮助
遇到不确定的参数，多用 --help 检查。在 Batocera 这种精简系统中，这也是最可靠的文档来源。

玩转命令行：路径与语法的生存法则

在掌握了基础连接后，我们来聊聊如何正确地向系统下达指令。虽然命令行看起来像一串乱码，但它其实有着非常严谨的逻辑。

1. 指令的基本“句式”

大多数命令行工具都遵循一套通用的语法模版，就像英语中的主谓宾结构一样：
<程序名称> -<功能开关（Option flags）> <运行参数> <输入文件路径> <输出文件路径>

生活化类比：这就像是你给厨师下达指令：厨师（程序） -切丝（开关）用快刀（参数）把土豆（输入）变成土豆丝（输出）。当然，并不是所有工具都完全按这个套路出牌，所以在“开火”之前，查阅说明书（manual）总是明智的。

2. 你在哪？——认识工作目录

当你登录 SSH 时，系统默认会把你放在“家目录（HOME folder）”里，路径是 /userdata/system。

识别符号：在终端窗口中，你会看到一个 ~ 符号，它就是“家”的缩写。
自查位置：如果你迷路了，只需输入 pwd（显示工作目录）并回车，系统就会告诉你当前具体在哪个房间。

3. 两种寻找文件的方法：绝对与相对

在命令行中指定文件位置（路径）时，有两种表达方式。如果搞混了，系统会提示找不到文件。

绝对路径（Absolute paths）：
无论你身在何处，这种路径永远指向同一个地方。它们总是以 / 开头。
- 例如：/userdata/saves（就像是写明了“中国北京XX区XX路”，无论你在哪，目的地都不变）。
相对路径（Relative paths）：
它是根据你当前所在位置来计算的。
- 例如：如果你正站在 /userdata 目录下，输入 nano system/batocera.conf，系统会去当前目录下的 system 文件夹里找文件。（这就像是说“去隔壁房间”，如果你换了地方，“隔壁”指代的位置也就变了）。

4. 处理特殊的文件名

【注意】：如果你的文件夹名字或文件名里带有空格或者特殊字符，必须给它戴上“头盔”——也就是在名字两边加上单引号 ' 或双引号 "。

生活化类比：这就像如果一个人的名字叫“王小明”（中间带空格），你点名的时候如果不加引号，系统可能会以为你要找“王”和“小明”这两个人。加上引号后，系统才会明白这是一个整体。

正确示范：cd "My Games" 或 nano 'super mario.txt'

紧急刹车与文件操作基础

当你开始在命令行中驰骋，掌握如何“停下来”以及如何管理文件是生存的基本功。

1. 紧急停止与快捷键秘籍

在执行指令时，如果你发现情况不对或者任务运行太久，可以使用快捷键强制干预。

如何强行停止任务？
按下 [Ctrl]+[C]。这就像是一个“紧急制动按钮”，可以立刻切断正在运行的程序。
> 【注意】：请谨慎使用！如果程序正写到一半，强行断开可能会导致数据损坏，就像在存盘时拔掉电源一样风险巨大。
SSH 里的复制与粘贴：
既然 [Ctrl]+[C] 被用来关程序了，那怎么复制文字呢？
- 复制：直接用鼠标选中文字。在大多数 SSH 工具中，选中即代表自动存入你的电脑剪贴板。
- 粘贴：在窗口中点击鼠标右键即可。

2. 强大的“午夜指挥官”：可视化管理

如果你觉得敲命令管理文件太累，Batocera 内置了一个强大的“正统文件管理器（Orthodox File Manager）”——Midnight Commander（简称 MC）。

第一步：启动工具
在终端输入 mc 并回车。
第二步：开始操作
你会看到一个蓝色的双面板界面。你可以用它来移动、复制、删除、重命名和编辑文件，甚至还能创建文件夹、制作符号链接（Symbolic links，即快捷方式）或修改文件权限。
> 【提示】：别看它长得像上个世纪的产物，它其实非常先进，甚至支持鼠标点击操作！

3. 文件管理“小抄”：基础指令集

除了图形化工具，直接使用 Unix 标准指令（Unix commands）会让你显得更像高手：

指令	英文全称	功能描述	举例说明
pwd	Print Working Directory	查看当前位置：告诉系统打印出你现在所在的文件夹路径。	如果你先进入了 `/userdata`，输入 `pwd` 就会显示 `/userdata`。
cd	Change Directory	切换目录：改变你当前所在的工作文件夹。	输入 `cd /userdata/roms` 就会把你传送到游戏 ROM 存放区。

生活化类比：pwd 就像是打开手机地图看“我的位置”，而 cd 则是输入目的地后进行“导航跳转”。掌握了这两个指令，你就永远不会在系统的层层文件夹中迷路。

文件管理实战：常用指令速查手册

掌握了如何“走路”（切换目录）之后，我们来看看如何“搬运”和“查看”你的文件。这些指令是你在 Batocera 后台进行维护时的必备工具。

1. 常用文件指令表

指令	英文全称	功能描述	举例说明
cp	CoPy	复制：将指定的文件或文件夹备份到另一个位置。	`cp /userdata/system/batocera.conf /userdata/batocera.conf` 会在 `userdata` 目录下创建一个配置文件的副本。
du -sh	Disk Usage	容量查看：显示指定文件夹占用的磁盘空间。`-sh` 参数表示“特定路径”且“易于阅读”。	`du -sh /userdata/roms/snes` 会告诉你超级任天堂游戏目录到底占了多少空间。
ls	LiSt	列出清单：显示当前文件夹下所有的文件和子文件夹。	如果你在 `/userdata/` 下输入 `ls`，你会看到 `bios`、`cheats`、`roms` 等一堆文件夹。
mkdir	MaKe DIRectory	新建文件夹：在当前位置创建一个新的目录。	`mkdir content` 会在当前目录下变出一个名为 `content` 的新文件夹。

2. 深度解析：为什么我的游戏大小显示不对？

【提示】：如果你从 Windows 电脑上通过文件管理器查看 Batocera 的文件，你可能会发现“文件大小”和“占用空间”这两个数值对不上，尤其是在玩 Wine（模拟 Windows 环境）游戏时。

生活化类比：这就像是一个真空包装的枕头。它的“实际尺寸”可能很大，但在衣柜里“占用的地方”却很小。du -sh 指令就像是一个精准的卷尺，它测出的是文件在 Batocera 硬盘上真实占据的物理空间。

3. 操作技巧

第一步：看一眼
在进行任何搬运操作前，先用 ls 确认文件是不是真的在那儿。
第二步：建个窝
如果你要整理文件，先用 mkdir 把新文件夹准备好。
第三步：做备份
修改重要配置前，记得用 cp 备份一份原始文件，这样就算改错了也能随时还原。
第四步：查空间
如果发现系统运行缓慢或者无法存盘，赶紧用 du -sh 检查一下是不是 ROM 塞得太满，导致磁盘空间告急了。

文件整理进阶：移动、重命名与删除

在掌握了基础查看指令后，接下来的这几项操作能让你像整理书架一样高效地管理 Batocera 里的游戏和配置文件。

1. 核心操作指令表

指令	英文全称	功能描述	举例说明
mv	MoVe	移动或重命名：将文件搬到新家，或者直接给它换个名字。	`mv /userdata/roms/gb/game.zip /userdata/roms/gbc` 会把游戏从 GB 文件夹挪到 GBC 文件夹。
nano	N/A	文本编辑器：在黑框界面里直接修改文件内容。	`nano /userdata/system/batocera.conf` 会打开配置文件让你直接编辑。
rmdir	ReMove DIRectory	删除空文件夹：只有文件夹里“空无一物”时才能成功。	`rmdir content` 会删掉名为 `content` 的空文件夹。
rm	ReMove	彻底删除文件：直接抹除指定的文件，不可撤销。	`rm screen.png` 会删掉当前目录下那张截图。
rm -r	ReMove Recursive	递归删除目录：连同文件夹及其内部所有文件一并抹除。	【超高风险】：执行后系统不会询问你，直接“连根拔起”！

2. 深度解析：身兼两职的 `mv` 指令

生活化类比：mv 指令就像是一个搬家工人。如果你告诉他一个新地址，他会把箱子搬过去（移动）；如果你告诉他一个新名字，他会顺手在箱子上贴个新标签（重命名）。如果你既给新地址又给新名字，他就能在搬家的同时完成改名。

3. 编辑文件：使用 `nano` 编辑器

如果你需要修改系统设置，nano 是最亲民的选择。

第一步：打开文件
输入 nano 加上文件路径。
第二步：修改内容
直接使用键盘光标移动并打字修改。
第三步：保存并退出
按下 Ctrl + O（保存），然后按 Enter（确认），最后按下 Ctrl + X（退出编辑器）。

4. 删除操作的安全警示

【注意】：在命令行中删除文件，没有“回收站”！

删除单个文件：使用 rm，操作前请反复核对文件名。
删除整个文件夹：使用 rm -r。

【警告】：rm -r 是一个非常危险的工具。它就像是一把威力巨大的“化骨绵掌”，只要一掌下去，目标文件夹及其内部成千上万的文件都会瞬间消失，且系统不会弹出任何确认窗口。在使用它之前，请务必停顿三秒，确认路径是否正确。

文件解压与 Batocera 商店管理

掌握了文件的移动和删除后，接下来我们将学习如何处理压缩包，以及如何通过命令行玩转 Batocera 的“应用商店”。

1. 解压缩指令：unzip

当你下载了游戏包或补丁时，通常需要用到解压功能。

基础解压：
输入 unzip file.zip，这会将 file.zip 里的所有内容直接“倒”在当前目录下。
指定位置解压：
使用 -d 选项（Directory）。例如：unzip file.zip -d uncompressed。这会创建一个名为 uncompressed 的新文件夹，并将内容解压到其中。

生活化类比：这就像拆快递。基础解压是直接在客厅地板上拆开，东西散落一地；而 -d 选项则是先拿个空箱子，把快递里的东西整齐地放进新箱子里。

2. Batocera 商店（内容下载器）

这是从 Batocera v29 版本开始引入的便捷功能，让你可以像在手机应用商店一样通过指令安装预设的游戏或工具。

指令	功能说明
batocera-store list	查看清单：列出所有可供下载的包（预配置的游戏等）。
batocera-store install <包名>	一键安装：下载并安装指定的软件包。
batocera-store list-repositories	仓库列表：查看当前配置的所有数据源地址。
batocera-store refresh	刷新列表：从服务器同步最新的商店目录。
batocera-store update	全量更新：把所有已安装的包升级到最新版本。
batocera-store clean	清理缓存：清除商店运行时的临时数据。
batocera-store clean-all	彻底大扫除：清除缓存的同时删掉下载的原始安装包。

3. 系统调试（Debugging）

当你需要深入系统底层寻找故障原因时，这些调试指令就是你的“听诊器”。

【注意】：在运行以下大部分调试命令之前，必须先输入 export DISPLAY=:0.0 并回车。

生活化类比：这就像是给系统插上显示器。因为很多图形化的调试工具需要知道往哪里“画图”，这条指令就是明确告诉系统：“请把接下来的画面显示在主屏幕上”。

第一步：环境初始化
输入 export DISPLAY=:0.0。
第二步：运行调试指令
此时，你就可以运行后续的系统调试工具来检测你的 Linux 操作系统了。

系统体检：排查与监控常用指令

当你的 Batocera 遇到声音不出、画面不对或者运行卡顿时，这些调试指令就是你的“全能工具包”。

1. 音视频硬件检测

如果你发现电脑版 Batocera 没声音或者分辨率不对，先用这两条指令给硬件做个“核磁共振”。

aplay -l：音频设备清单。它会列出系统识别到的所有播放硬件。如果这里是空的，那说明驱动或硬件连接出了问题。
xrandr：显示设备调节器。它能告诉你当前连接了哪些显示器，以及它们支持的所有分辨率和刷新率。
vulkaninfo：Vulkan 接口调试。用于查看显卡对 Vulkan API 的支持详情，这对于运行 3D 游戏至关重要。

2. 存储与系统监控

blkid：磁盘扫描仪。它会列出所有当前连接到机器上的可挂载驱动器（如 U 盘、硬盘）。如果你找不到外置存储，用它准没错。
htop / btop：任务管理器。
- htop：基础款，能看清 CPU、内存占用。
- btop：进阶款，界面更酷炫，信息更详尽。

生活化类比：这两款工具就像是系统的“仪表盘”。你可以通过它们一眼看出是不是哪个程序在后台“偷跑”，把系统资源给吃光了。

3. 进程管理：锁定并关闭程序

有时候某个游戏卡死了，你需要像“外科医生”一样精准地切除故障程序。

第一步：锁定身份标识
使用 pidof 命令。例如输入 pidof RetroArch，如果程序正在运行，它会返回一串数字（即 进程标识符（PID））。
第二步：执行终止操作
使用 kill [PID]。如果上一步得到的数字是 640，那么输入 kill 640 就能强行结束这个程序。

生活化类比：PID 就像是每个程序的“身份证号”。因为系统里可能运行着好几个名字相似的程序，通过身份证号（PID）来关掉它（kill），才不会误伤其他正常的任务。

4. 进阶探针

kill -0 [PID]：这是一个非常有用的“生命探测仪”。
- 操作方式：输入 kill -0 640。
- 功能：它并不会真的杀掉进程，而是去确认这个身份证号对应的程序是否还“活着”。如果程序还在运行，它不会有任何报错；如果程序已经彻底崩溃或关闭，系统会提示找不到该进程。

进程搜索与系统增强工具

在掌握了精准“杀掉”某个程序的技巧后，我们再来看看如何在大堆任务中快速揪出目标，以及如何给老版本的 Batocera 升级监控工具。

1. 查找指令进阶

如果你不确定程序的精确名字或身份证号，可以用这两个指令来搜索。

pgrep：进程模糊搜索。它的工作原理类似于在文档中搜索关键词，只不过它是针对正在运行的程序。
- 例如：输入 pgrep emul*，系统会帮你找出所有名字里包含 emul 的程序 ID，比如游戏菜单界面（EmulationStation）及其相关的脚本。
which：定位运行路径。它能告诉你某个指令对应的程序文件到底藏在硬盘的哪个角落。
- 例如：输入 which python，它会显示出 Python 这个程序的安装路径。

生活化类比：pgrep 就像是在茫茫人海中喊“姓王的人请举手”，它能帮你缩小范围；而 which 则像是一个精准的地图坐标，告诉你“王小明”这个程序文件具体住在哪条街（路径）。

2. 在旧版本（v33 及更早版本）中安装 btop 监控

btop（及其 Python 前身 bpytop）是一款非常华丽且强大的系统资源监控器。

【提示】：从 Batocera v34 开始，系统已经自带了 btop。你只需在命令行输入 btop 即可（如果显示乱码，请尝试输入 btop --utf-force）。但如果你还在使用 v33 或更早版本，则需要按照以下步骤手动安装。

安装步骤：

第一步：升级包管理器
在终端运行：python -m ensurepip --upgrade
第二步：安装监控工具
运行：pip3 install bpytop --upgrade
第三步：保存系统状态
因为 Batocera 的系统目录在重启后会还原，所以必须运行：batocera-save-overlay 来固化你的修改。

【注意】：由于 Batocera 的系统特性，每次当你升级了 Batocera 系统版本后，你都需要重新执行一遍上述安装步骤。

3. Batocera 专属指令：控制游戏主界面

在 Batocera 中，有一个非常有用的专属指令，可以让你安全地关闭整个游戏菜单系统。

/etc/init.d/S31emulationstation stop：强制停止游戏界面。

生活化类比：这就像是直接拉下了游戏大厅的电闸。通常在你需要手动修改一些系统核心文件，或者需要彻底释放系统资源进行底层操作时，会用到这条指令。

Batocera 特色工具箱：界面、鼠标与系统信息

除了标准的通用指令，Batocera 还内置了一系列专门定制的“瑞士军刀”工具，让你能更方便地控制游戏界面和显示设置。

1. 界面控制与屏幕显示

界面重启与唤回：
- 指令 A：batocera-es-swissknife --restart
  第一步：执行该指令以启动或重启游戏菜单界面（EmulationStation）。
  第二步：如果你想回到终端继续操作，只需按下 [Ctrl] + [C]，界面会保持运行，而控制权会交还给你的命令行窗口。
- 指令 B：/etc/init.d/S31emulationstation start
  这是启动界面的另一种方式。同样，按下 [Ctrl] + [C] 可以让你在不关闭游戏界面的情况下回到终端。
鼠标指针开关：
- 显示鼠标：使用 unclutter-remote -s（Show）。
- 隐藏鼠标：使用 unclutter-remote -h（Hide）。

2. 系统信息与配置修改

查看名片：batocera-info
运行此命令会打印出你登录系统时看到的那些版本和状态信息。
快捷改配置：batocera-settings
这是一个自动化修改配置文件的工具。它能让你在不手动打开文本编辑器的情况下，直接通过命令行修改系统参数。
支持包生成：batocera-support
如果你在论坛寻求帮助，技术大牛可能会让你提供一份“支持数据包（Support tarball）”，运行此命令即可自动打包你的系统日志和配置。

3. 屏幕分辨率与手柄检测

【注意】：在使用显示相关的指令前，请务必先输入 export DISPLAY=:0.0 并回车。

显示分辨率列表：batocera-resolution listModes
它会列出所有可用的显示模式。这和你直接在游戏界面的“视频模式（Video mode）”选项中看到的列表是一一对应的。
分辨率指令总览：batocera-resolution
如果你不确定具体的参数，直接输入这个命令，它会向你展示所有与分辨率和显示相关的可选指令。
手柄信息查询：batocera-padinfo
用来查看当前连接的手柄（Controller pads）信息。

【提示】：在 Batocera v32 版本中，由于手柄输入驱动（Input driver）的架构发生了变动，batocera-padinfo 可能会出现无法正常显示信息的情况。

4. 小结：Batocera 的“特异功能”

生活化类比：如果说标准的 Linux 指令是“万能扳手”，那么这些以 batocera- 开头的指令就是针对你这台“游戏机”定制的“专用模具”。它们能跳过复杂的底层逻辑，直接帮你完成开关界面、调整屏幕、检测手柄等最常用的操作。

屏幕分辨率调优：Batocera 显示控制指南

在处理屏幕黑边、分辨率不匹配或想要切换显示器时，这些特定的分辨率管理工具将非常有用。

【注意】：在运行以下所有指令前，请确保已执行过 export DISPLAY=:0.0。

1. 分辨率与模式切换

第一步：查看可选模式
输入 Batocera-resolution listModes。
它会列出所有你的屏幕支持的显示模式。你会发现这个列表和你在游戏主界面的“视频模式（Video mode）”中看到的一模一样。
第二步：设置目标模式
使用 Batocera-resolution setMode <模式名称>。
- 例如：如果你想强制锁定在 1080p，可以参考列表输出后的名称输入，如 Batocera-resolution setMode max-1920x1080。

2. 查看当前显示状态

如果你觉得画面看起来怪怪的，可以用这两条指令来“查岗”：

查询详细模式参数：Batocera-resolution currentMode
它不仅会显示分辨率，还会显示当前的刷新率（Refresh rate）和时序（Timings）等底层信息。
查询实时输出分辨率：Batocera-resolution currentResolution
直接告诉你当前正发送到显示屏上的画面像素大小。

生活化类比：currentResolution 就像是问投影仪“你现在投出来的画面有多大”，而 currentMode 则是更详细地检查投影仪的亮度、帧数和对焦参数。

3. 多显示器与输出端口管理

如果你的机器接了多个屏幕（比如笔记本接了电视，或者 PC 接了两个显示器），可以用以下指令进行切换。

第一步：列出所有接口
输入 Batocera-resolution listOutputs。
你会看到类似 HDMI-1、DP-1 或 eDP-1 这样的名称。
第二步：切换输出屏幕
使用 Batocera-resolution setOutput <接口名称>。
- 例如：如果你想把画面切换到 HDMI 接口，输入 Batocera-resolution setOutput HDMI-1。

4. 强制分辨率上限（兼容性说明）

Batocera-resolution minTomaxResolution <宽度>x<高度>：
这个指令的作用是设定一个“天花板”，防止系统尝试开启超过此规格的高清模式。
- 例如：输入 Batocera-resolution minTomaxResolution 1280x720，如果系统试图运行 1080p，它会被强行拉回到 720p 运行。

【注意】：该指令在 Batocera v32 及更高版本 中已经过时。现在的推荐做法是直接使用 setMode 指令（例如 setMode max-1920x1080）来精准控制分辨率上限。

屏幕进阶调优与开发者工具箱

在掌握了常规分辨率切换后，如果你需要更精准的画面控制，或者想要像开发者一样排查系统状态，接下来的这两组工具将是你的进阶法宝。

1. 强制自定义显示模式

有时候，系统预设的模式列表里没有你想要的选项，这时你可以动用“强权”指令。

Batocera-resolution forceMode <水平像素>x<垂直像素>:<刷新率>
该指令会手动创建一个自定义的显示参数（Modeline）并强制显示器运行。
- 例如：输入 Batocera-resolution forceMode 1920x1080:60 会强制开启 1080p 60Hz 模式。

【注意】：由于这是跳过系统自动检测的强制操作，如果你输入的参数超出了显示器的承受范围，可能会导致黑屏或显示异常。在操作前，请确保你非常清楚显示器的硬件极限。

2. Batocera ES 瑞士军刀（开发者工具）

为了方便系统开发和高级调试，Batocera 提供了一个名为 Batocera-es-swissknife 的多功能工具（简称 ES 瑞士军刀）。你可以通过运行 Batocera-es-swissknife --help 查看完整说明。

以下是截至 v32 版本的常用功能开关（Flag）：

指令开关	功能描述
–restart	仅重启界面：只重新启动游戏主菜单（EmulationStation）。
–kodi	启动 Kodi：关闭游戏界面并立即开启 Kodi 媒体中心。
–reboot	重启系统：让整个机器重新启动。
–shutdown	关机：彻底关闭整个系统。
–emukill	强杀游戏：强制关闭当前正在运行的任何模拟器。
–espid	查询 ES 身份：检查游戏主界面是否活跃。如果返回 `0` 表示未运行，否则会返回其真实进程标识符（PID）。
–emupid	查询模拟器身份：检查是否有模拟器正在运行。它返回的是 `emulatorlauncher.py` 的 PID。
–arch	查看架构：显示当前系统运行的硬件架构（如 x86_64）。
–version	查看版本：显示当前 Batocera 的具体版本号。
–update	检查更新：查看是否有可用的系统更新。

3. 操作小贴士

第一步：环境确认
在执行涉及画面的 forceMode 之前，请记得先运行 export DISPLAY=:0.0。
第二步：故障排除
如果你的游戏界面卡死，无法通过手柄操作，可以从另一台电脑通过 SSH 登录并运行 Batocera-es-swissknife --restart 来拯救它。

生活化类比：Batocera-es-swissknife 就像是游戏机背后的“紧急维护面板”。即使前台的按钮都失灵了，你依然可以通过这个面板直接控制电源、重启系统，或者查看系统现在的“户籍信息（PID/版本）”。

系统维护与格式化工具：危险但强大的“底层手术刀”

在掌握了日常管理和调试后，我们进入最后一部分，涉及系统底层修改、备份以及磁盘格式化。

1. 开发者工具箱（进阶补充）

在使用 Batocera-es-swissknife 时，还有几个针对系统核心的高级开关。

更新频道切换：
默认情况下，系统处于“稳定版（stable）”。你可以通过指令指定不同的频道。
- 操作方式：输入 Batocera-es-swissknife --update butterfly 可以切换到实验性的“蝴蝶版（butterfly）”。
系统覆盖层备份：
使用 --overlay 开关。系统会尝试为你手动修改过的覆盖层文件（Overlay file）制作备份。
读写权限切换：
使用 --remount 开关（默认针对 /boot 目录）。
> 【注意】：这条指令会切换系统目录的“只读/可写”状态。这就像是解开了系统的“防写锁”，操作不当可能会导致系统配置损坏，产生严重后果。
重置模拟器设置：
使用 --reset-ra 开关。它会将所有的 RetroArch 模拟器设置（RA settings）还原为默认状态。

2. 磁盘格式化工具：极高风险

【注意】：这是一个极度危险的区域。错误的操作会导致你的数据永久消失！

生活化类比：格式化工具就像是“降维打击”。一旦启动，指定区域内的所有数据都会被彻底抹除。在使用这些指令前，请务必确认你已经做好了数据备份。

帮助说明：输入 batocera-format --help。系统会弹出一个（拟人化的）警告信息。
磁盘清理步骤：
- 第一步：查看磁盘清单
  运行 batocera-format listDisks，列出当前机器上所有可以被格式化的分区和硬盘。
- 第二步：查看可选格式
  运行 batocera-format listFstypes，查看 Batocera 支持将磁盘格式化为什么类型（如 ext4, btrfs 等）。
- 第三步：执行格式化（慎用！）
  运行 batocera-format format <磁盘名> <文件系统类型>。执行后，该硬盘上的所有内容将瞬间销毁。
特殊指令：仅格式化内部数据区：
如果你只想重置内部硬盘的数据分区（userdata），而不动系统分区，可以使用：
batocera-format format INTERNAL <文件系统类型>。

3. 驱动器健康检查（SMART）

为了防止硬盘突然“罢工”，你还可以使用 SMART 健康检查 工具。它可以实时监控硬盘的物理状态，预警潜在的硬件故障。

【提示】：定期检查磁盘健康状况，就像是给硬盘做“体检”，可以在数据丢失前发现坏道或硬件疲劳的征兆。

硬盘健康管家：S.M.A.R.T. 状态检查

就像我们要定期体检一样，硬盘也有自己的健康报告机制，叫做 S.M.A.R.T. 自动检测分析报告技术（Self-Monitoring, Analysis and Reporting Technology）。

通过这些工具，你可以查看硬盘的“病历卡”，提前发现硬件故障的苗头。

【提示】：Batocera 自 v34 版本起已内置了 smartctl 工具。如果你在网上搜索教程，可以直接跳过安装步骤，直接开始操作。

1. 磁盘识别与信息查询

在检查之前，我们需要先确定硬盘的“编号”。

第一步：列出磁盘
输入 lsblk。
系统会列出所有磁盘，请找到你的目标磁盘名称（通常是类似 sda 或 nvme0n1 这样的代号）。
第二步：查看磁盘基本信息
输入 smartctl -i /dev/sdx（请将 sdx 替换为你的磁盘名）。
这会显示磁盘的型号、序列号等身份证信息。
第三步：快速体检
输入 smartctl -H /dev/sdx。
系统会用一个单词告诉你磁盘现在的健康等级（例如 PASSED 表示合格）。

2. 深度检测与全量报告

如果你怀疑硬盘有问题，可以使用更详尽的诊断命令。

查看完整报告：输入 smartctl --all /dev/sdx。这会打印出所有详细的 S.M.A.R.T. 技术参数。
运行快速运输测试：输入 smartctl -t conveyance /dev/sdx。这会进行一个约 5 分钟的短程测试，通常用于检测磁盘在运输过程中是否受损。
运行特定扇区测试：输入 smartctl -t select,100-150 /dev/sda。这对磁盘的特定区域（如编号 100 到 150 的区域）进行针对性扫描。

生活化类比：smartctl -H 就像是问医生“我身体好吗？”，医生回答你“挺好”；而 --all 则像是拉出了一张写满各项指标的血液检查报告单。

【注意】：检测需适度。频繁运行深度的磁盘测试会增加硬盘负担，请仅在必要时使用。

3. 互联网与系统更新

Batocera-upgrade：
这是通过命令行进行系统升级或降级的核心工具。

操作感句式：
第一步：确保你的 Batocera 已经联网。
第二步：输入 Batocera-upgrade 配合正确的 URL 链接，系统就会自动开始获取并安装新版本。

关于手动升级或降级的更多细节，可以查阅专门的“手动升级/降级”页面。

系统的安装与软件包管理：打造你的定制版 Batocera

在掌握了日常维护和磁盘检查后，最后我们来学习如何通过命令行安装系统以及管理额外的软件包。这些工具能让你绕过图形界面，更直接地进行底层部署。

1. 系统安装指令集（Batocera-install）

如果你想把 Batocera 部署到新的硬盘上，可以使用这一套高效的安装命令。

第一步：寻找目标磁盘
输入 Batocera-install listDisks。
系统会列出当前所有可用于安装系统的磁盘。这和你直接在游戏界面的“将 Batocera 安装到新磁盘”选项中看到的内容是一样的。
第二步：获取支持的架构清单
输入 Batocera-install listArchs。
程序会连接网络，下载并显示目前 Batocera 官方支持的所有稳定版硬件架构（例如 x86_64, RPi4 等）。
第三步：执行安装
使用 Batocera-install install <磁盘代号> <架构名|本地文件>。
系统会自动下载并安装最新的稳定版。如果你想安装特定的离线包，需要先将文件放入 /userdata/system/installs 目录下。

【注意】：执行安装操作会彻底摧毁目标磁盘上的所有现有数据！在按下回车键之前，请像确认存折密码一样仔细核对磁盘代号。

辅助指令：如果你不确定本地有哪些安装包，输入 Batocera-install listFiles 即可列出 /userdata/system/installs 目录下的所有文件。

2. 软件包管理器：Pacman 指令速查

Batocera 引入了强大的 Pacman 软件包管理器（Package Manager），让你可以像在电脑上装软件一样扩展系统功能。

指令	功能描述	操作建议
pacman -Ss	搜索软件：在服务器仓库中根据关键词寻找你需要的软件包。	想装某个软件但不确定全名？先用它搜一下。
pacman -S	同步并安装：根据软件名直接下载并安装到系统中。	找到准确名称后，一键安装。
pacman -Rsd	移除软件：根据名称卸载软件包。	`R` 代表移除，`s` 代表递归处理，`d` 代表跳过依赖检查。

生活化类比：Pacman 就像是一个智能的“外卖配送员”。你告诉他想吃什么（-Ss 搜索），他就会去后厨仓库找，然后帮你取货并送到家门口安装好（-S 安装）。如果你不需要了，他也能负责帮你把餐盒撤走（-Rsd 移除）。

3. 进阶学习建议

【提示】：关于软件包管理的更多进阶技巧和注意事项，建议查阅专门的“Batocera 软件包管理器（pacman）”详细文档。

通过这些命令，你已经从一个普通玩家进阶成了能够熟练操控 Batocera 底层系统的“高级指挥官”。无论是远程维护、性能排查还是系统重装，命令行都将是你最强大且最高效的武器。

软件包清理与命令结果导出指南

在掌握了安装与卸载后，最后我们来学习如何维护软件包管家的健康，以及如何把命令运行的结果“记在纸上”。

1. 软件包管家（Pacman）的日常维护

随着你安装的软件越来越多，软件包管理器（Package Manager）会产生一些临时数据。学会清理和更新它是保持系统清爽的关键。

指令	英文全称（缩写含义）	功能描述
pacman -Scc	Sync, clear Cache	彻底清除缓存：删掉软件包管家下载的所有安装包缓存。第二个 `c` 表示强制完全清空。
pacman -Sy	Sync, refresh y	刷新数据库：从服务器获取最新的软件清单，确保你能搜到最新版本的软件。

生活化类比：pacman -Scc 就像是清空家里的“快递包装盒回收站”。这些盒子（缓存）在装好软件后就没用了，定期清空可以腾出不少宝贵的硬盘空间。

2. 将命令结果保存到文件（重定向）

有时候命令输出的内容太多，在黑色窗口里翻页看很不方便，或者你想把结果存起来备份。这时我们可以使用“重定向”符号。

生活化类比：默认情况下，命令的结果是“直接说给你听”（显示在屏幕上）；使用重定向符号后，就像是让系统“把话写在纸上”（存入文件）。

第一步：确定输出目标
使用 > 符号。它会将命令的结果导向一个文件。如果该文件已存在，它的内容会被覆盖。
第二步：执行导出
例如，你想把当前目录下所有的文件列表存入一个叫 list-files.txt 的文件里，只需输入：
ls > /userdata/system/list-files.txt
第三步：查看结果
执行后，终端屏幕不会显示任何内容，但你会发现在 /userdata/system 目录下多了一个文本文件，里面整齐地记录着刚才的列表。

【注意】：如果你连续两次运行同一个 > 命令，第二次的结果会把第一次的内容完全抹除掉。如果你想在原有内容的后面“接着写”，请使用双箭头 >> 符号。

结果处理与系统进阶工具

在学会了如何将信息保存到文件之后，我们还要掌握如何“追加”内容以及如何处理那些长得一眼看不完的命令结果。

1. 结果的“覆盖”与“追加”

在上一节中，我们学会了用 > 把结果写进文件。但如果你想把多次运行的结果都保存下来，就需要用到 >>。

追加内容（Appending）：
使用 ls >> /userdata/system/list-files.txt。
> 生活化类比：如果 > 是把旧黑板擦干净再写新内容，那么 >> 就像是在笔记本的下一行接着记录。之前的旧信息会保留，新的结果会排队跟在后面。

2. 使用“管道”连接不同程序

有时候一个命令产生的信息量巨大（比如几千行日志），屏幕根本显示不下。这时我们可以用管道符号（Pipe，即垂直线 |）把数据传给另一个“阅读器”程序。

第一步：选择你的“阅读器”
- 逐行阅读模式：输入 dmesg | less。你可以使用键盘的 [上]/[下] 箭头自由滚动查看。
- 逐页阅读模式：输入 dmesg | more。按 [空格键] 翻到下一页。
第二步：退出阅读
无论使用哪种模式，只要按下 [Q] 键即可退出，回到命令行界面。

生活化类比：这就像是消防栓喷出的水流（原始数据）太猛，你没法直接喝。管道符号 | 就像接上了一根水管，把水引到饮水机（less 或 more）里，让你能一小口一小口地慢慢喝。

3. Batocera 趣味与实用脚本

Batocera 还内置了一些方便的小工具，让你能轻松记录精彩的游戏瞬间。

屏幕截图：执行 Batocera-screenshot，系统会将当前画面保存到 /userdata/screenshots 文件夹。
屏幕录制：执行 Batocera-record 开始录像。当你录完时，按下 [Ctrl]+[C] 即可停止。
同步管理：使用 Batocera-sync list 可以查看目前有哪些存储设备支持同步功能。

4. 硬件超频设置（Overclocking）

【注意】：此功能目前仅支持树莓派（RPi）和 s922 平台。

查看选项：输入 Batocera-overclock list 查看你的硬件支持哪些超频挡位。
执行超频：使用 Batocera-overclock set <数值> 来保存并应用超频设置。

【重要警告】：超频就像是给赛车强行打氮气，虽然速度变快，但也可能导致硬件不可逆转的损坏或系统行为异常。所有的超频操作风险自负。如果设置后系统变得不稳定，请务必第一时间将其恢复为默认值。

数据同步、时区调节与自定义快捷指令

在进阶操作的最后，我们将学习如何同步你的珍贵数据，调整系统时间，以及如何通过“起外号”的方式让复杂的指令变得过目不忘。

1. 数据同步：给你的存档买份保险

如果你想把当前系统的数据同步到外部存储设备，可以使用内置的同步工具。它在底层使用了 远程同步（rsync） 技术，能够高效地对比并传输文件。

操作指令：batocera-sync <存储设备 UID>
系统会将当前的“用户数据（userdata）”同步到目标设备的 batocera/ 文件夹下。

【注意】存储格式限制：
* 不支持同步到 NTFS 格式的分区。
* 如果目标设备是 FAT 系列格式（如 FAT32），同步后将无法保留蓝牙设置信息。

2. 时区设置：别让系统“过错时间”

如果你的游戏存档时间显示不对，通常是因为时区（Timezone）没有设置正确。

查看当前时区：输入 batocera-timezone get。
自动探测时区：输入 batocera-timezone detect。系统会尝试根据你的网络环境自动猜测你所在的位置。
手动精确设置：使用 batocera-timezone set <国家或洲/城市或区域>。
- 例如：设置为中国标准时间，可以输入 batocera-timezone set Asia/Shanghai。

3. 自定义别名：给复杂指令“起外号”

如果你觉得某些指令太长、太难记，你可以使用 别名（Alias） 功能。

生活化类比：这就像是给手机里的长号码设置“一键拨号”。你只需要按下一个简单的数字（外号），系统就会自动拨打那个长长的号码（复杂指令）。

虽然这不是必须的，但在 /userdata/system 目录下创建一个名为 .profile 的文本文件，可以让你拥有这种超能力。

设置步骤：

第一步：创建/编辑配置文件
在 /userdata/system 下新建一个名为 .profile 的文件。
第二步：编写别名指令
别名的标准格式如下：
alias 你的自定义外号='原本的长指令'
- 例如：你想通过输入 check 就查看配置文件的占用空间，可以写成：
  alias check='du -sh /userdata/system/batocera.conf'
第三步：保存并重启
由于 .profile 文件会在系统启动时自动加载，因此修改后需要重启 Batocera 才能生效。

【提示】：请务必小心操作 .profile 文件。因为它在启动时自动执行，如果里面写错了指令，可能会导致你的终端环境出现异常。

进阶技巧：打造你的自定义“一键指令”

在上一节中，我们提到了如何为长指令起“外号”。一旦你重启 Batocera，这些自定义别名就会正式生效。

1. 别名实战：简单查容量

继续之前的例子，当你成功设置了名为 customname 的别名后：

操作感句式：
只需在命令行输入 customname 并回车，系统就会自动执行 du -sh /userdata/system/batocera.conf。
运行结果：
终端会立刻告诉你这个配置文件的大小。这就像给复杂的文件夹路径设了一个“快捷键”。

2. 高阶实战：为 PC 版定制“截图快捷键”

在树莓派（Raspberry Pi）上截图很容易，但在 x86_64 设备（普通电脑版）上，系统缺少自带的简易截图工具。我们可以利用强大的 多媒体处理工具（FFmpeg） 编写一个名为 pc2jpeg 的别名，实现一键截图并自动按时间命名。

别名代码：
alias pc2jpeg='ffmpeg -hide_banner -loglevel error -f x11grab -i :0.0 -frames:v 1 /userdata/screenshots/$(date +%y-%m-%d_%H-%M-%S).jpg'

生活化类比：FFmpeg 就像是一个万能的“数字录像机”。这个复杂的别名指令本质上是告诉录像机：“不要说废话（隐藏版本信息），除非出错了再叫我，现在对着 0 号屏幕按一下快门，然后把照片塞进截图文件夹，名字记得贴上今天的日期和时间。”

3. 拆解这串“魔法咒语”

如果你好奇这串长指令具体做了什么，这里是它的详细清单：

ffmpeg：这是 Batocera 内置的命令行转码与处理神器。
-hide_banner：清爽模式。运行时不会弹出那一大串版权声明。
-loglevel error：安静模式。只有在截图真的失败时，才会在屏幕上显示报错。
-f x11grab -i :0.0：抓取目标。告诉系统使用 x11grab 驱动来捕获当前的 0 号屏幕（即你的主显示器）。
-frames:v 1：快门次数。告诉录像机只抓取 1 帧画面（即一张静态照片）。
/userdata/screenshots/$(date …).jpg：保存路径。利用 date 命令自动生成形如“年-月-日_时-分-秒”的文件名，确保每张截图都不会重名。

4. 如何使用

第一步：按照上一节的方法，将上述 alias 代码写入 /userdata/system/.profile 文件。
第二步：重启系统。
第三步：以后任何时候想截图，只需在终端输入 pc2jpeg，一张高清剧照就存进你的 screenshots 文件夹啦！

深度解析：自动化命名与别名的魅力

在上一节的“一键截图”案例中，那串复杂的路径其实隐藏着一个非常聪明的自动化逻辑。

1. 自动重命名背后的“魔法”

指令中最后一段 /userdata/screenshots/$(date +%y-%m-%d_%H-%M-%S).jpg 是截图文件的保存路径。

关键组件：$(date …)
这是一个命令替换操作。它就像是一个“变量翻译官”，会先在后台偷偷运行一次 date 命令，然后把结果立刻填回原来的位置。
- 举例说明：如果你在 2020 年 12 月 31 日 21 点 52 分 19 秒按下回车，这串代码就会变成 20-12-31_21-52-19。
- 最终路径：系统读取到的实际路径就是 /userdata/screenshots/20-12-31_21-52-19.jpg。

生活化类比：这就像是你去冲印照片，不用自己手写日期，相机（系统）会自动在照片背后的“文件名”位置盖上一个极其精确的时间戳。这样你截多少张图都不会因为重名而互相覆盖。

2. 为什么还要学这个？

【提示】：细心的玩家可能发现了，现在的 Batocera 已经内置了 Batocera-screenshot 指令来实现类似功能。

那为什么还要保留这个例子呢？
因为这个例子完美展示了 自定义别名（Alias） 的强大语法。学会了它，你就可以根据自己的需求，把任何复杂的“多行指令”浓缩成一个简单的“小外号”，极大提升你在命令行下的操作效率。

3. 遇到困难怎么办？

如果你在尝试这些进阶操作时遇到了问题，或者系统反馈了你看不懂的报错信息：

第一步：保持冷静
大多数命令行错误都有迹可循，检查一下空格、单引号或路径是否输入正确。
第二步：查阅故障排除指南
请访问官方文档中的故障排除（Troubleshooting）相关章节，那里有针对常见问题的详细解答和补救措施。

生活化类比：命令行就像是一台精密的老式打字机，虽然对输入要求很严格，但只要你掌握了它的脾气，它就是你管理 Batocera 最可靠的得力助手。

原文: SSH连接Batocera教程 • 翻译: DIY8 Bot

文章版权归作者所有，未经允许请勿转载。