Atmosphère 自定义固件配置指南从 stratosphere.ini 到 system_settings.ini 的完整调校手册【免费下载链接】AtmosphereAtmosphère is a work-in-progress customized firmware for the Nintendo Switch.项目地址: https://gitcode.com/GitHub_Trending/at/AtmosphereAtmosphère 是一套面向 Nintendo Switch 的进行中定制固件custom firmware它通过若干位于 SD 卡上的 INI 配置文件把内核与安全监控器行为、用户态系统模块、开机画面、按键覆盖Override甚至每个应用程序的行为标志全部开放给用户自行调校。本文以仓库文档 docs/features/configurations.md 为核心骨架逐一讲解stratosphere.ini、emummc.ini、exosphere.ini、override_config.ini、system_settings.ini五大配置文件与 Content Specific Flags 的格式、语法、可用取值并结合仓库源码印证其底层解析逻辑。读完本文你将能够安全、正确地修改 Atmosphère 的默认行为例如控制卡带读取器保护、替换开机画面、绑定按键快捷启动 Homebrew Menu以及通过system_settings.ini覆盖任意系统固件设置。配置文件总览Atmosphère 的配置体系由以下文件构成它们在启动流程的不同阶段、由不同的组件读取配置文件作用组件SD 卡位置默认模板stratosphere.inifusée引导阶段配置用户态系统模块/atmosphere/config/config_templates/stratosphere.iniemummc.iniemummceMMC 存储模拟/emuMMC/由 emuMMC 项目提供exosphere.iniexosphère安全监控器SD 卡根目录config_templates/exosphere.inioverride_config.ini引导阶段的 Override 解析/atmosphere/config/config_templates/override_config.inisystem_settings.ini系统固件设置覆盖/atmosphere/config/config_templates/system_settings.ini所有模板都位于 config_templates/ 目录下升级固件时可作为还原默认值的参考。stratosphere.ini配置用户态系统模块stratosphere.ini是 fusée 在引导阶段读取、用于配置用户态系统模块的配置文件位于 SD 卡的/atmosphere/config/目录。它目前的核心配置项是 nogc 保护。nogc 卡带读取器保护nogc 是 fusée-secondary 提供的一项功能用于禁用 Switch 的 Game Card卡带读取器。其目的是当主机在未烧录熔丝不 burning fuses的情况下从较低固件版本升级时防止读取器被随之更新。具体而言固件版本 4.0.0 与 9.0.0 都引入了对卡带读取器固件的更新因此升级到这些版本之后的主机存在读取器被顺带更新的风险。默认情况下 Atmosphère 会自动决定是否保护读取器但用户可以手动强制指定。在stratosphere.ini的[stratosphere]小节添加如下行即可[stratosphere] nogc X取值含义1 强制启用 nogcAtmosphère 将始终禁用卡带读取器0 强制禁用 nogcAtmosphère 将始终启用卡带读取器。模板文件 config_templates/stratosphere.ini 中给出了对应的注释写法[stratosphere] ; To force-enable nogc, add nogc 1 ; To force-disable nogc, add nogc 0源码视角nogc 的解析与自动决策从源码结构看nogc 的判定逻辑位于 fusée 的 fusee_setup_horizon.cpp。IsNogcEnabled()首先尝试解析 SD 卡上的sdmc:/atmosphere/config/stratosphere.ini只关心[stratosphere]小节并取nogc键的首字符是否为1作为强制开关entry.value[0] 1。如果 INI 中未显式配置则进入自动决策分支函数读取主机的熔丝版本fuse version并与当前目标固件所期望的熔丝版本fuse::GetExpectedFuseVersion逐一比对。只要目标固件不低于 12.0.2、11.0.0、9.0.0 或 4.0.0 且熔丝版本偏低就返回true启用 nogc。这与文档中4.0.0 / 9.0.0 起引入读取器固件更新的说法一致且覆盖了后续更多固件版本。随后该结果被传入 fusee_stratosphere.cpp 的ConfigureStratosphere()在构建 package2 时决定是否追加对应的 nogc KIP 补丁。添加自定义开机启动画面Atmosphère 自带默认启动画面即上文 img/splash.png在开机时显示但用户可以随意替换。开机画面必须为 1280x720 分辨率。仓库源码树中提供了插入脚本 utilities/insert_splash_screen.py用法如下python insert_splash_screen.py path to your splash screen image path to /atmosphere/package3 on your SD card即第一个参数是你的启动画面图片路径第二个参数是 SD 卡上/atmosphere/package3的路径。脚本会就地in-place改写该文件因此建议先备份原始package3。脚本的底层细节从 insert_splash_screen.py 的实现可以了解其工作方式图片会被打开并转换为RGBA若宽高为 1280x720 则先旋转 90°transpose(Image.ROTATE_90)随后断言宽 720、高 1280像素被逐行打包为BGRA字节序pack(BBBB, b, g, r, a)每行按 768 像素的 stride 补齐SPLASH_SCREEN_STRIDE 768目标package3必须满足两个硬性校验文件头魔数为PK31且总长度为0x800000字节生成的画面数据长度为0x3C0000字节被写入package3中偏移0x400000处替换原有的默认画面段。因此只要提供一张合规的 1280x720 图片脚本就能保证画面段被准确替换不会破坏 package3 其余部分的结构。emummc.inieMMC 模拟配置emummc.ini是 emummc 组件eMMC 存储模拟的配置文件位于 SD 卡的/emuMMC/目录。emummc 是一个协作项目为 Switch 提供 eMMC 存储模拟能力使定制固件可以运行在模拟的系统存储之上。详细的功能说明见 docs/components/emummc.md而该组件的具体配置项与使用说明由 emuMMC 项目本身维护仓库中emummc目录即为集成实现例如其入口 emummc/main.c 与 eMMC 驱动 emummc/source/emmc/nx_emmc.c。请以 emuMMC 项目提供的文档为准进行配置。exosphere.ini安全监控器配置exosphere.ini是 exosphère运行于安全世界、负责密钥管理与电源管理等职责的安全监控器使用的配置文件位于SD 卡根目录默认模板见 config_templates/exosphere.ini。配置调试模式默认情况下Atmosphère 会向 Horizon 内核发出调试已启用的信号同时保持用户态调试处于禁用状态。但这种组合可能带来不期望的副作用。如需改变在exosphere小节修改对应键值[exosphere] debugmode X debugmode_user X取值含义1 启用0 禁用模板文件给出的默认值为debugmode1、debugmode_user0。请注意模板中的警告禁用debugmode会破坏 Atmosphère 本身Disabling this will break Atmosphere因此不建议修改该键。exosphere.ini 的完整键表config_templates/exosphere.ini 中实际上给出了比文档更完整的可用键整理如下键默认值含义debugmode1控制内核是否为调试模式禁用会破坏 Atmosphèredebugmode_user0控制用户态是否为调试模式disable_user_exception_handlers0控制出错时是否执行用户态异常处理器关闭会导致 Atmosphère 无法优雅失败不建议修改enable_user_pmu_access0控制用户态是否有 PMU 寄存器访问权限对官方代码的影响未知blank_prodinfo_sysmmc0是否在 sysMMC 环境中清空 PRODINFOblank_prodinfo_emummc0是否在 emuMMC 环境中清空 PRODINFOallow_writing_to_cal_sysmmc0是否允许 Homebrew 在 sysMMC 中写入 PRODINFO强烈不建议开启log_port0exosphère 日志使用的 UART 端口0UART-A、1UART-B、2UART-C、3UART-Dlog_baud_rate115200日志波特率0 会被视为 115200log_inverted0日志 UART 端口是否反相清空 PRODINFOBlanking PRODINFOAtmosphère 允许用户在模拟 eMMCemuMMC或系统 eMMCsysMMC环境中清空出厂校准数据 PRODINFO对应键即为上表中的blank_prodinfo_sysmmc与blank_prodinfo_emummc。模板中的说明指出启用后系统会看到被哑化的密钥与序列号信息但这些数据可能被系统在其他位置缓存安全性未知因此文档明确表示不建议使用Usage is not encouraged。同样地allow_writing_to_cal_sysmmc也带有强烈警示开启后 Atmosphère 会在未使用的 MMC 空间内以加密形式保存一份校准数据备份用于在紧急情况下防止不可恢复的修改但除非你有妥善的外部备份否则不要开启。override_config.ini按键覆盖Overridesoverride_config.ini位于/atmosphere/config/目录默认模板见 config_templates/override_config.ini。该文件在引导过程中被解析默认情况下不配置任何内容。它的用途是把特定按键绑定到特定功能上例如启动 Homebrew MenuHBL或启用金手指cheat管理器。合法按键表override_config.ini中的override_key条目可选用以下合法按键注意 INI 名称区分大小写正式名称.ini 名称A ButtonAB ButtonBX ButtonXY ButtonYLeft StickLSRight StickRSL ButtonLR ButtonRZL ButtonZLZR ButtonZR ButtonPLUS- ButtonMINUSLeft DpadDLEFTUp DpadDUPRight DpadDRIGHTDown DpadDDOWNSL ButtonSLSR ButtonSR反转行为!前缀若要反转覆盖键的行为请在按键名前面加一个感叹号!。反转后按住该按键启动时进入的是实际游戏而不是 Homebrew Menu。例如override_key!R含义为只有按住 R 键启动时才运行游戏本体否则不按 R启动 Homebrew Menu。配置完成后将 SD 卡重新插回 Switch 并正常启动 Atmosphère即可通过启动你指定的程序来进入 Homebrew Menu。模板中的高级用法程序级配置模板 config_templates/override_config.ini 展示了比文档更完整的结构包括[hbl_config]与[default_config]两个小节[hbl_config] ; Up to 8 program-specific configurations can be set. ; These use program_id_#, override_address_space_#, and override_key_# ; where # is in range [0,7]. ; program_id_0010000000000100D ; override_address_space39_bit ; override_key_0!R ; Any Application Config ; override_any_apptrue ; override_any_app_keyR ; override_any_app_address_space39_bit ; pathatmosphere/hbl.nsp [default_config] ; override_key!L ; cheat_enable_key!L要点最多可配置8 个程序级配置编号#范围为[0, 7]对应program_id_#、override_address_space_#、override_key_#override_any_app可对未被上面程序级配置指定的任意应用程序统一生效path指定 Homebrew Menu 的加载路径如atmosphere/hbl.nsp[default_config]中的override_key是全局默认覆盖键cheat_enable_key用于绑定金手指的开关按键。源码视角按键解析从 cfg_override.board.nintendo_nx.inc 的ParseOverrideKey()可以看到上述 18 个按键名到内部HidNpadButton位标志的一一映射如A→HidNpadButton_A、LS→HidNpadButton_StickL、DLEFT→HidNpadButton_Left等。关键行为是若值以!开头则设置override_by_default true并跳过该字符——这正是反转语义的实现与文档描述完全一致。同一文件中的ParseOverrideAddressSpace()L153-L174还支持解析地址空间覆盖39_bit默认对应 64 位地址空间、36_bit、32_bit以及32_bit_without_alias等别名。OverrideConfigIniHandler()L188 起则负责把hbl_config/default_config小节中的program_id_#、override_key_#、override_address_space_#等条目逐个填入覆盖配置结构体此外程序级配置还支持放置在/atmosphere/contents/program_id/config.ini中按程序单独覆盖见 L370。system_settings.ini覆盖固件调试设置system_settings.ini位于/atmosphere/config/目录默认模板见 config_templates/system_settings.ini。Atmosphère 通过它在引导期间覆盖系统固件使用的调试设置。它是一个普通 INI 文件但有特定的解释规则。设置标识符与值格式系统设置的标准标识符形如name!key在system_settings.ini中表示为小节name 条目key。例如[name] key ...由于设置可以有多种变量类型字符串、整型、字节数组等system_settings.ini必须把值存储为type_identifier!value_store对。一个完整示例把设置eupld!upload_enabled设为 0[eupld] upload_enabled u8!0x0重要警告格式错误的值字符串会导致开机时触发致命错误fatal error。修改前务必小心。支持的类型system_settings.ini支持以下三种类型族字符串Strings类型标识符str、string值字符串直接作为设置内容使用并追加空终止符。整型Integral types类型标识符u8、u16、u32、u64值字符串通过strtoul(value, NULL, 0)解析0基数因此同时支持十进制与0x十六进制写法位宽由标识符决定u8为 1 字节、u16为 2 字节依此类推。原始字节Raw bytes类型标识符hex、bytes值字符串按十六进制字符串解析值字符串长度必须为偶数否则解析时会抛出致命错误。模板中的常用设置实例config_templates/system_settings.ini 提供了大量可直接启用的实战示例按小节整理如下[eupld]—— 关闭错误报告上传[eupld] ; Disable uploading error reports to Nintendo ; upload_enabled u8!0x0[usb]—— 强制 USB 3.0 超速模式[usb] ; 0 USB 3.0 support is system default (usually disabled), 1 USB 3.0 support is enabled. ; usb30_force_enabled u8!0x0[ro]—— 放宽 NRO 校验[ro] ; Control whether RO should ease its validation of NROs. ; ease_nro_restriction u8!0x1[lm]—— 日志管理器输出到 SD 卡[lm] ; enable_sd_card_logging u8!0x1 ; sd_card_log_output_directory str!atmosphere/binlogs[erpt]—— 保留错误报告[erpt] ; disable_automatic_report_cleanup u8!0x0[atmosphere]—— Atmosphère 自定义设置最常用的一节[atmosphere] ; 开机致命错误后自动重启的间隔毫秒数缺省或为 0 时无限等待用户输入 ; fatal_auto_reboot_interval u64!0x0 ; 电源菜单重启按键行为normal 为普通重启rcm 为 RCM 重启payload 为重启到 payload ; power_menu_reboot_function str!payload ; dmnt 金手指默认开关状态1 默认开启0 默认关闭 ; dmnt_cheats_enabled_by_default u8!0x1 ; dmnt 是否总是保存金手指开关状态1 总是保存0 仅在开关文件存在时保存 ; dmnt_always_save_cheat_toggles u8!0x0 ; 允许 HBL 写入 BIS 分区正常使用下不建议开启 ; enable_hbl_bis_write u8!0x0 ; 允许 HBL 读取 CAL0 分区正常使用下不建议开启 ; enable_hbl_cal_read u8!0x0 ; fs.mitm 是否把存档文件重定向到 SD 卡目录实验性不建议随意开启 ; fsmitm_redirect_saves_to_sd u8!0x0 ; am 是否把系统设置 DebugModeFlag 视为启用0 关闭1 启用 ; enable_am_debug_mode u8!0x0 ; dns.mitm 总开关0 关闭1 开启 ; enable_dns_mitm u8!0x1 ; dns.mitm 是否在用户 hosts 文件基础上附加默认重定向0 仅用 hosts1 默认 hosts ; add_defaults_to_dns_hosts u8!0x1 ; dns.mitm 是否向 SD 卡写调试日志 ; enable_dns_mitm_debug_log u8!0x0 ; htc 总开关开启时日志管理器被强制视为开启 ; enable_htc u8!0x0 ; Atmosphère 日志管理器总开关 ; enable_log_manager u8!0x0 ; 蓝牙配对数据库是否重定向到 SD 卡sysMMC 与所有 emuMMC 共享 ; 注意13.0.0 之前数据库大小为 10 而非 20低于 13.0.0 的固件启动会截断数据库 ; enable_external_bluetooth_db u8!0x0[hbloader]—— Homebrew 堆配置[hbloader] ; 以 applet 方式运行时 Homebrew 堆的大小为 0 时使用全部可用 applet 内存默认为 0 ; applet_heap_size u64!0x0 ; 以 applet 方式运行时为其他 applet 预留的内存量applet_heap_size 非零时无效默认 0x8600000 ; applet_heap_reservation_size u64!0x8600000从仓库源码可以确认这类设置的消费方遍布各系统模块例如 fs_mitm_service.cpp 会先读取atmosphere!fsmitm_redirect_saves_to_sd的设置值再结合下文介绍的redirect_save内容标志决定是否把存档重定向到 SD 卡[atmosphere]小节中的enable_dns_mitm、enable_log_manager等则由对应模块dns_mitm、LogManager在启动时读取。Content Specific Flags按程序定制行为除了全局配置文件Atmosphère 还支持基于 SD 卡上标志文件flag的存在与否来定制 CFW 行为。方法是在目录/atmosphere/contents/program_id/flags/内放置名为flag_name.flag的文件其中program_id为目标程序的 16 位十六进制 Program ID。当前支持以下标志boot2指示该程序应在boot2进程期间被启动redirect_save指示该程序希望将其存档数据重定向到 SD 卡。源码视角两个标志的实际消费点boot2标志在 boot2_api.board.nintendo_nx.cpp 中boot2 遍历 SD 卡上的程序时会通过cfg::HasContentSpecificFlag(program_id, boot2)检查该标志只有带此标志的程序才会被纳入启动流程并进一步检查其 mitm 列表。redirect_save标志在 fs_mitm_service.cpp 中fs.mitm 处理存档访问时会先检查系统设置atmosphere!fsmitm_redirect_saves_to_sd是否为真再检查当前程序是否带redirect_save标志——两者同时满足才执行存档重定向。这解释了为何该功能被标记为实验性它需要配置文件与程序标志双重配合。标志文件的底层查找逻辑位于 cfg_flags.board.nintendo_nx.inc其拼接的路径格式正是/atmosphere/contents/%016llx/flags/%s.flag与文档描述的目录结构一致。使用注意事项格式错误 致命错误system_settings.ini中任何一个格式错误的值例如hex类型长度不是偶数、类型标识符拼写错误都会导致开机 fatal修改后务必逐字核对PRODINFO 操作有风险清空 PRODINFOblank_prodinfo_sysmmc/blank_prodinfo_emummc与允许写入 CALallow_writing_to_cal_sysmmc均被官方标注为不建议使用数据可能被系统缓存到其他位置务必先做好完整备份debugmode不可随意关闭模板明确指出禁用debugmode会破坏 Atmosphère 本身实验性开关需谨慎fsmitm_redirect_saves_to_sd、enable_hbl_bis_write、enable_hbl_cal_read等设置直接放开对 BIS/系统分区的访问或改动存档路径仅适合了解其后果的高级用户所有修改需重启生效配置文件均在引导阶段被解析override_config.ini、system_settings.ini 在 boot 过程解析stratosphere.ini 由 fusée 解析exosphere.ini 由 exosphère 读取修改后重启主机即可生效备份优先替换/atmosphere/package3自定义开机画面属于就地写操作请先备份原文件。通过本文的配置项与源码印证你现在可以按需组合上述机制用stratosphere.ini固定卡带读取器策略、用override_config.ini定制按键启动行为、用system_settings.ini覆盖任意固件设置并借助 Content Specific Flags 实现按程序的精细化定制。【免费下载链接】AtmosphereAtmosphère is a work-in-progress customized firmware for the Nintendo Switch.项目地址: https://gitcode.com/GitHub_Trending/at/Atmosphere创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考