Atmosphere 定制固件上手：从源码构建到上机启动的 5 个关键点
Atmosphere 定制固件上手：从源码构建到上机启动的 5 个关键点
项目地址: https://gitcode.com/GitHub_Trending/at/Atmosphere 给 Switch 装完一次系统更新后，你可能发现老游戏开始闪退，或者你一直想玩金手指、跑 homebrew，又不想动真机 eMMC 里的存档。Atmosphere（Atmosphère）就是做这件事的 Switch 定制固件：它逐层替换系统组件，让你可以在 SD 卡上运行虚拟系统、注入自定义系统模块、管理金手指。这篇文章带你把它从源码构建成可运行的产物，并解释几个真正影响日常使用的配置。
🔧 它解决什么问题
Atmosphere 的设计思路是"分层替换"：Switch 固件每一层（引导加载、安全监视器、NAND、内核、系统模块、应用层）都被对应组件替换或修改，任何一层出问题都只影响那一层。核心组件共六个，按大气层命名：
- Fusée — 一级引导加载器，负责加载、校验并修补后续阶段的 TrustZone 和内核包
- Exosphère — 自定义安全监视器，运行在最高特权模式
- Thermosphère — EL2 层 EmuNAND 支持，实现 NAND 镜像的虚拟化与重定向
- Mesosphère — 内核实现
- Stratosphère — 自定义系统模块，扩展内核能力并 hook 关键系统行为
- Troposphère — 应用层的 Horizon OS 补丁，实现具体 CFW 功能
🚀 五分钟构建出来
构建依赖几乎全部来自 devkitPro 生态，先按 devkitPro 官方指南装好 devkitA64 和 devkitARM 工具链，然后执行下面三组命令：
# 用 dkp-pacman 安装 Switch 目标工具链和构建依赖
dkp-pacman -S switch-dev switch-glm switch-libjpeg-turbo devkitARM devkitarm-rules hactool
# 安装 LZ4 Python 库，exosphere 构建脚本需要
pip install lz4
# 克隆仓库并在根目录执行 make 完成全部组件构建
git clone https://gitcode.com/GitHub_Trending/at/Atmosphere
cd Atmosphere && make
可选依赖：PyCryptodome（部分加密步骤用到）。Python 2 或 3 均可，官方未保证 Python 3 全兼容。构建产物按组件散落在各子目录，部署到 SD 卡的目录结构可参考 docs/features/configurations.md 中对各配置文件位置的描述。
📦 核心能力速览
虚拟系统（emuMMC）：把整个 NAND 重定向到 SD 卡上的镜像，系统更新、存档、密钥都发生在镜像里，真机 eMMC 保持不动。配置入口是 /emuMMC/ 下的 emummc.ini，进程能力定义见 emummc/emummc.json。
金手指：支持 Action-Replay 风格代码，且自带一套重写过的虚拟机——修复了原版条件指令的多个 bug、支持嵌套条件块，还新增了浮点运算指令。代码文件放在 /atmosphere/contents/<program_id>/cheats/ 下，按 build_id 命名。
系统模块替换：stratosphere/ 下每个子目录都是一个可独立编译的系统模块（loader、pm、fs、sm 等），同名替换系统自带模块，这是 Atmosphere 能 hook 系统行为的基础。
调试与日志：串口日志（exosphere 可配 UART 端口和波特率）、SD 卡日志（LogManager 模块）、cheat VM 调试日志三种通道。
⚙️ 按需调整配置
所有默认模板在 config_templates/，SD 卡上的实际位置：exosphere.ini 放 SD 卡根目录，其余放 /atmosphere/config/。下面四个是最常被动的：
; exosphere.ini — 开启用户态调试模式（默认 0）
; 什么时候改：调试 homebrew 或抓用户进程崩溃时
[exosphere]
debugmode_user = 1
注意 debugmode = 1 是硬依赖，注释里写明了关掉会直接破坏 Atmosphere。
; stratosphere.ini — 强制禁用游戏卡读卡器（nogc 保护）
; 什么时候改：想防止系统更新时读卡器固件被烧写、又不想烧 fuse 时
[stratosphere]
nogc = 1
; system_settings.ini — 禁止向任天堂上报错误报告
; 什么时候改：在意隐私、不希望 fatal 信息上传时
[eupld]
upload_enabled = u8!0x0
; override_config.ini — 按住 R 启动游戏时进入 homebrew 菜单
; 什么时候改：需要常驻 homebrew 入口、或改金手指启用按键（cheat_enable_key 同理）
[hbl_config]
path=atmosphere/hbl.nsp
override_any_app_key=R
其余项（blank_prodinfo_*、log_port、enable_log_manager 等）含义都写在模板注释里，建议对着 config_templates/exosphere.ini 逐个看，其中 PRODINFO 空白功能的注释明确提示"不鼓励使用"。
❓ 高频问题速查
| 现象 | 最可能原因 | 快速处理 |
|---|---|---|
make 报工具链相关错误 | devkitA64/devkitARM 未装或 dkp-pacman 包缺失 | 对照 docs/building.md 的依赖清单逐项安装 |
| 开机直接 fatal 退出 | system_settings.ini 值格式错误（文档明确：malformed 值会直接 fatal） | 与 config_templates/ 逐项比对，注意 type!value 格式 |
| 金手指不生效 | cheat 路径或 build_id 不对，或没按启用键 | 文件须为 /atmosphere/contents/<program_id>/cheats/<build_id>.txt，参考 docs/features/cheats.md |
| 系统更新后卡带读卡器仍被更新 | 未开启 nogc 保护 | stratosphere.ini 中设 nogc = 1 |
如果改完配置反而开不了机，优先怀疑 system_settings.ini：它的取值是 类型!值 的强解析（如 u8!0x0），一个字符写错就会在启动阶段 fatal，而不是静默忽略。
🧩 进阶玩法
- 自定义启动画面：替换 1280x720 的开机图，源码树里有现成脚本 utilities/insert_splash_screen.py，用法见 docs/features/configurations.md。
- 写自己的系统模块：
stratosphere/下每个模块都是"源文件 +system_module.mk+*.json"三件套，照着stratosphere/erpt/这种最小模块抄结构即可。 - 深入 emuMMC 配置：多镜像、多系统切换的细节看 emummc/ 目录下的实现与 docs/features/configurations.md 的 emummc.ini 章节。
🌐 生态与社区
随仓库分发的四个库是二次开发的主要入口：libexosphere（安全监视器 API）、libmesosphere（内核层）、libstratosphere（系统模块开发）、libvapours（工具库），全部位于 libraries/。项目由 SciresM、TuxSH、hexkyz 和 fincs 维护，社区入口（Discord 邀请）写在 README.md 里。
先把 config_templates/ 的模板原样拷进 SD 卡对应位置，别凭记忆改配置。动 nogc、debugmode_user 之前确认你知道默认值，改坏了删掉该行即可恢复默认。构建产物和文档一起看，docs/changelog.md 记录了每个版本的变动。下一步把产物部署到 SD 卡，用全默认配置冷启动一遍，确认无误后再逐项加配置。
北京人形旗下天工造物具身智能开源社区，聚焦具身天工与慧思开物两大平台
更多推荐
3
0- 0
已为社区贡献18条内容
所有评论(0)