OnionOS 定制系统从零到一安装教程：Miyoo Mini 掌机升级上手指南
【免费下载链接】OnionOS overhaul for Miyoo Mini and Mini+项目地址: https://gitcode.com/gh_mirrors/on/Onion
刚把 Miyoo Mini 从包装盒里拿出来那天，我对着原厂界面发了好一会儿呆：功能说不上有错，可总感觉这台小掌机藏着没被挖出来的潜力。直到朋友丢过来一句"试试 OnionOS 定制系统"，我才意识到，原来给这台机器换一套系统，就能从"能玩"直接跳到"很好玩"——内置 100 多个模拟器、自动存档断点续玩、主题和工具随手换。这篇 Miyoo Mini 定制系统安装教程，就是照着我亲手踩过的坑写的，你顺着走一遍，就能把系统装好、让游戏跑起来。
换系统前后：一次升级，两种完全不同的体验
原厂固件更像"开箱即用"的样板间：能住，但处处留白。OnionOS 是把整个操作体验重做了一遍的定制系统，官方默认与它之间的差距，用一张表就能看明白：
| 对比项 | 原厂默认系统 | OnionOS 定制系统 |
|---|---|---|
| 模拟器阵容 | 数量有限 | 100+ 内置模拟器，FC、GB、GBA、PS1 等主流平台全覆盖 |
| 存档方式 | 手动折腾 | 自动保存 + 断点续玩，关机前不用惦记进度 |
| 界面主题 | 固定一套 | 主题可随意更换，社区资源丰富 |
| 系统工具 | 几乎没有 | 电池监控、活动追踪、包管理器等一应俱全 |
| 更新维护 | 等厂商 | 跟随社区版本持续迭代 |
说白了，官方默认系统是"够用"，OnionOS 是"好用"。换一次系统，相当于给掌机换了个更聪明的大脑。
开机画面的变化是最直观的"换代证据"——装上 OnionOS 之后，点亮屏幕看到的将不再是原厂那张一成不变的图：
出发前先对照这张检查单，三分钟省掉一小时
装系统本身不复杂，但前提条件少一条，后面就可能多踩一个坑。动手之前，先逐项打钩：
- 一台 Miyoo Mini 或 Miyoo Mini+（本教程以这两款型号为准）
- 一张靠谱的 SD 卡：强烈建议换掉原装卡，改用 SanDisk、三星等品牌的 32GB 或 64GB 高速卡。原装卡速度慢，轻则游戏卡顿，重则存档丢失
- 读卡器和电脑（Windows / macOS / Linux 都可以）
- 固件不要太旧：进入设备"设置 > 设备信息 > 版本"查看，OnionOS 需要较新的原厂固件支撑
- OnionOS 安装包：从发布页下载
Onion-v4.x.x.zip，或用命令拉取仓库源码
git clone https://gitcode.com/gh_mirrors/on/Onion这份清单里最容易让人栽跟头的是第二项。如果手里只有原装卡，建议先买张新卡再开工，这笔投入绝对值得。
闯关式安装：三关走完，OnionOS 就装好了
我把整个安装过程拆成三个关卡，每关开头写了"通关目标"，结尾给了"验证方法"，做完就知道自己有没有走错。
第一关：给 SD 卡"搬家"，把安装文件放进去
通关目标：得到一张装满 OnionOS 安装文件、随时能插进掌机的 SD 卡。
第一步，把 SD 卡格式化成 FAT32（注意，不是 exFAT）：
- Windows：用 Rufus 工具，引导类型选"非引导"，分区方案选 MBR，文件系统选"大容量 FAT32"，簇大小设 32KB，点开始
- macOS：打开"磁盘工具"，选中 SD 卡，点"抹掉"，格式选 MS-DOS (FAT)，方案选"主引导记录"
- Linux：用 GNOME 磁盘工具格式化，或命令行
mkfs.vfat，文件系统选 FAT
第二步，解压安装包，把 7 个文件夹整体复制到 SD 卡根目录：
.tmp_update/ BIOS/ Media/ miyoo/ miyoo354/ RetroArch/ Themes/其中.tmp_update是隐藏文件夹，复制前记得打开"显示隐藏文件"：Windows 在资源管理器"查看"里勾选"隐藏的项目"，macOS 按 Command+Shift+.，Linux 用ls -a确认。
拷贝完毕，插卡开机后，系统会先用一个引导页跟你打个招呼：
验证方法：在电脑上点开 SD 卡，能看到上面 7 个文件夹（包括隐藏的.tmp_update），第一关就通过了。
第二关：第一次点亮屏幕，让系统自己装自己
通关目标：一台跑着 OnionOS 定制系统、能正常开关机的掌机。
- 把 SD 卡插进掌机，长按电源键开机
- 系统自动开始安装，全程不用你动手
- 装完会弹出 Quick Guide（快速指南），相当于系统自带的说明书
- 接着进入 Package Manager（包管理器），勾选想启用的系统和应用，按 START 两次确认
- 全部完成后按 A 键，机器会关机或重启
安装引导里有一页专门讲游戏列表的用法，装完后你马上就会用到它：
验证方法：重启后能看到全新的主界面，不再是原厂那套菜单；在"游戏"标签页按 SELECT 能弹出刷新选项，就说明系统已经成功接管掌机。
第三关：把游戏请进门，让列表出现你的收藏
通关目标：一台真正能玩游戏的完整掌机。
- 把游戏 ROM 按平台放进
Roms目录下对应的子文件夹，常见的有 FC、SFC、GB、GBA、PS 等 - 部分模拟器需要 BIOS 文件，统一放进
BIOS文件夹（原装卡的RetroArch/.retroarch/system目录里能翻出不少） - 回到主界面"游戏"标签页，按 SELECT 选择"刷新所有游戏"，等扫描完成
验证方法：刷新后游戏列表里能看到你放进去的游戏；随便挑一个按 A 启动，能正常进入游戏画面，这一关就通关了。如果某个游戏进不去，九成是缺 BIOS，回到第 2 步补上即可。
装完只是开始：这些加分项值得挨个开一遍
系统能跑了，接下来才是最好玩的部分。所有"锦上添花"的功能都集中在这一章，按兴趣挑着用就行。
主题切换器：让界面长成你喜欢的样子
在"应用"里打开主题切换器（Theme Switcher），浏览可选主题、选中后一键应用，界面立刻变样。换主题是入门门槛最低、视觉反馈最直接的一项，强烈建议第一个试。
包管理器：装应用、换模拟器核心
包管理器（Package Manager）相当于 OnionOS 的应用商店。第一次安装时你见到的就是它，之后随时能回来：加装应用、切换模拟器核心、更新组件，都在这里完成。
电池监控：心里有数，续航不慌
电池监控工具会把当前电量、本次会话时长、剩余时间估算画成图表。长途通勤想玩多久、出门要不要带充电宝，看一眼就有数。
游戏活动追踪：看看时间都花在哪个游戏上了
活动追踪会记录每个游戏的游玩时长和最近记录。想知道自己"到底在哪个游戏上投入最多"，打开它一目了然，还能反过来帮你规划碎片时间。
充电动画：连充电都变得赏心悦目
插上电源充电时，屏幕会显示一个发光的电池图标，随着电量上涨逐格点亮。等待充电不再是干瞪眼，反而成了观察系统细节的小乐趣。
新手最容易踩的五个坑：症状、原因、解法一次说清
坑 1：装到一半卡住不动
- 症状：开机后长时间停在同一个画面
- 原因：多半是 SD 卡没格式化干净，或者 7 个文件夹没拷全
- 解法：重新格式化为 FAT32，确认全部文件夹（含隐藏的
.tmp_update）都在根目录，再插回去重来
坑 2：找不到.tmp_update文件夹
- 症状：拷贝时看不到它，怀疑自己漏拷了
- 原因：它是隐藏文件夹，文件管理器默认不显示
- 解法：Windows 勾选"隐藏的项目"，macOS 按 Command+Shift+.，Linux 用
ls -a查看
坑 3：某个游戏进不去
- 症状：按 A 启动后黑屏或退回菜单
- 原因：缺对应模拟器的 BIOS 文件，或 ROM 格式不被支持
- 解法：先补 BIOS 到
BIOS文件夹，再确认 ROM 是模拟器支持的格式
坑 4：游戏列表里空空如也
- 症状：刷新之后还是看不到游戏
- 原因：ROM 没放进对应的平台子文件夹，或文件夹命名不对
- 解法：对照平台文件夹快速参考表确认路径，放对位置后重新刷新
坑 5：电池显示不准
- 症状：电量百分比与实际使用时间对不上
- 原因：统计被校准前的旧数据干扰
- 解法：在设置里重置电池统计，再用几次完整充放电循环让数据回归正常
最后有一条铁律必须单独拎出来：千万别手痒删除
.tmp_update文件夹。名字像临时文件，其实是系统核心，删了系统直接罢工。
装好了，接下来往哪走
走到这里，你的 Miyoo Mini 已经装上 OnionOS 定制系统，能玩、能换主题、有工具可用。回头看这一路：格式化一张卡、拷一遍文件、开一次机、放进游戏，四步而已。
接下来可以继续探索的方向：
- 整理游戏库：按平台分好 ROM，配合列表刷新，找游戏会越来越顺手
- 收藏喜欢的主题：在主题切换器里多试几套，界面风格随心情切换
- 吃透存档机制：熟悉自动保存与断点续玩，开荒多难的游戏都不怕掉进度
- 跟进系统更新：跟着版本升级，新功能和修复会陆续到来
想深入研究的，可以参考这些项目资料：
- 功能总览文档：website/docs/01-features/index.md
- 全新安装官方步骤：website/docs/02-installation/01-fresh-install.mdx
- 旧版本升级指南：website/docs/02-installation/02-upgrading.mdx
- 主题切换器源码：src/themeSwitcher/
- 电池监控工具源码：src/batteryMonitorUI/
- 游戏活动追踪源码：src/playActivityUI/
现在，把卡插回掌机，挑一款游戏，好好享受这套定制系统带来的复古游戏体验吧。🎮
【免费下载链接】OnionOS overhaul for Miyoo Mini and Mini+项目地址: https://gitcode.com/gh_mirrors/on/Onion
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
