在 Nintendo Switch 2 模拟器 Eglantine 中进行原生应用（homebrew / native application）开发时，真机调试往往繁琐且耗时。本篇技术指南基于用户手册中的 Native 章节 展开，讲解如何借助模拟器的调试能力（密钥集切换、序列号/电池编号自定义、GDB stub 等）让自研应用在模拟环境中"原样运行"，并结合仓库源码剖析密钥管理、序列号生成等底层实现，帮助你搭建一套可重复、可验证的调试工作流。

为什么用模拟器调试原生应用

在物理主机上调试应用通常需要反复刷机、抓取日志，流程冗长。Eglantine 的设计目标是让用户"利用模拟器的调试能力，确保其应用尽可能原样地在系统上运行"——也就是说，模拟器不仅用于玩游戏，也作为一个可控的、可复现的系统级测试环境。

结合用户手册中的 命令行参考，开发者常用的调试入口包括：

• --debug/-d：进入调试模式，允许 GDB stub 连接（默认端口1234为文档示例值）；
• --program/-p：指定传递给程序（homebrew）的参数，对应 Android 端设置中的 "Homebrew Args"，其说明为"启动时传递给 homebrew 的命令行参数（如-noglsl）"（见 strings.xml 中program_args_description）；
• --user/-u <number>：指定用户索引，便于验证多用户场景下的应用行为。

这些能力与下文两项调试配置配合，即可覆盖多数 homebrew 开发场景。

调试能力一：标准密钥前缀（切换密钥集）

文档原文给出的功能是Standard key prefix：允许将密钥管理器的目标文件从prod.keys重定向到其他文件（例如前缀other会加载other.keys），默认前缀为prod。这对"同时维护多套密钥集"的测试场景非常有用——例如一套正式密钥、一套开发密钥、一套特定固件版本的密钥，通过切换前缀即可在同一模拟器目录内共存而无需反复替换文件。

从源码结构看，密钥的实际加载逻辑集中在 KeyManager::ReloadKeys()：

void KeyManager::ReloadKeys() { // Initialize keys const auto keys_dir = Common::FS::GetEdenPath(Common::FS::EdenPath::KeysDir); if (!Common::FS::CreateDir(keys_dir)) LOG_ERROR(Core, "Failed to create the keys directory."); if (Settings::values.use_dev_keys.GetValue()) { dev_mode = true; LoadFromFile(keys_dir / "dev.keys_autogenerated", false); LoadFromFile(keys_dir / "dev.keys", false); } else { dev_mode = false; LoadFromFile(keys_dir / "prod.keys_autogenerated", false); LoadFromFile(keys_dir / "prod.keys", false); } LoadFromFile(keys_dir / "title.keys_autogenerated", true); LoadFromFile(keys_dir / "title.keys", true); LoadFromFile(keys_dir / "console.keys_autogenerated", false); LoadFromFile(keys_dir / "console.keys", false); }

由此可以梳理出密钥体系的完整加载顺序：

几个值得注意的实现细节：

1. 密钥统一存放在 Eden 路径体系下的keys目录（Common::FS::EdenPath::KeysDir，定义见 path_util.h），目录不存在时会自动创建；
2. 每个密钥文件都有对应的_autogenerated变体，且加载顺序是"先自动生成的、再手工放置的"，后加载者可覆盖同名键值——这为自动化注入密钥提供了约定；
3. use_dev_keys是一个布尔设置，声明于 settings.h（Category::Debugging），可在 Qt 前端的调试配置页勾选（见 configure_debug.cpp 中的ui->use_dev_keys绑定）；
4. 调试配置页应用设置后会立即调用Core::Crypto::KeyManager::Instance().ReloadKeys()（见 configure_debug.cpp），也就是说切换密钥集无需重启模拟器，立即生效。

因此，"密钥前缀"的实际含义是：选择加载哪一套*.keys文件集（prod/dev/ 自定义前缀），其底层入口就是ReloadKeys()中针对keys_dir的文件名选择。对 homebrew 开发者而言，推荐的工作流是：

• 为每个被测环境准备独立的密钥文件（如other.keys）；
• 按文档所述通过密钥前缀指向目标文件；
• 在调试设置页切换/确认后，ReloadKeys()会重新解析全部密钥文件，应用即可在新密钥集下运行。

调试能力二：修改序列号（Serial 与 Battery Number）

文档给出的第二个功能是Changing serial：以非常简单的方式设置 serial（序列号）和 battery number（电池编号）的调试值。要点有三：

• 开发者无需填写完整序列号，只需填写前几位数字（最后一位除外），末位校验位由系统自动补全；
• 区域设置会影响生成的序列号；
• 生成的序列号对应一台非 OLED / 非 Lite的主机。

这一描述在源码中有完整对应。序列号与电池编号由两个u32设置承载，声明于 settings.h：

Setting<u32> serial_battery{linkage, 0, "serial_battery", Category::Debugging}; Setting<u32> serial_unit{linkage, 0, "serial_unit", Category::Debugging};

序列号如何拼装：区域决定前缀，数字决定主体

当应用（或系统服务）向 SET 服务查询序列号时，ISystemSettingsServer::GetSerialNumber会基于serial_unit的数值拼装完整的SerialNumber，实现见 system_settings_server.cpp：

u32 d = ::Settings::values.serial_unit.GetValue(); SerialNumber c{}; c.serial_number[0] = 'X'; c.serial_number[1] = 'A'; c.serial_number[2] = [] { // Adding another setting would be tedious so... let's just reuse region_index :) switch (::Settings::values.region_index.GetValue()) { case ::Settings::Region::Japan: return 'J'; case ::Settings::Region::Usa: return 'W'; case ::Settings::Region::Europe: return 'E'; case ::Settings::Region::Australia: return 'M'; //pretend its Malaysia case ::Settings::Region::China: case ::Settings::Region::Taiwan: return 'C'; case ::Settings::Region::Korea: return 'K'; default: return 'W'; } }(); Fill3DS_CRC(d, c.serial_number.data() + 3);

这段代码精确解释了文档中的三条描述：

1. "前几位数字"规则：用户提供的数值d被逐位拆解写入序列号数字区，最后一位不写入——Fill3DS_CRC(d, ...)会基于各位数字的奇偶位加权和计算校验位（奇数位与偶数位求和，sum_digit = ((sum_even * 3) + sum_odd) % 10，非零时取10 - sum_digit，实现见 system_settings_server.cpp），即"最后一位由系统补全"；
2. "区域设置影响序列号"：序列号第三位由region_index直接映射（日版J、美版W、欧版E、澳版M、中/台版C、韩版K），源码注释也坦承"多加一个设置太麻烦，就复用 region_index"；
3. "非 OLED/Lite"含义：固定前缀XAW...形式对应标准版主机序列号格式（XAW/XAE等），而非 OLED 或 Lite 型号的前缀。

电池编号走类似路径：ISystemSettingsServer::GetBatteryLot（见 system_settings_server.cpp）以固定字母前缀BHACHHZZAD开头，第 10 位由serial_battery数值按(d / 100000) % 26映射为大写字母，末段同样使用Fill3DS_CRC计算校验位。

调试值从哪里填写

• GUI 方式：Qt 前端的调试配置页提供两个数字输入框，读写serial_battery与serial_unit（对应serial_battery_edit/serial_board_edit控件，见 configure_debug.cpp 与 configure_debug.cpp）；
• 配置文件方式：两者均为标准Setting，键名分别为serial_battery、serial_unit，默认值0，可在用户配置文件中直接指定。

零值时的自动生成机制

值得特别注意的是：serial_unit/serial_battery为0并不代表"无序列号"，而是触发随机生成。settings_generator.cpp 中的GenerateSettings()会为此兜底：

// Randomly generated number because, well, we fill the rest automagically ;) // Other serial parts are filled by Region_Index std::uniform_int_distribution<u32> distribution(1, (std::numeric_limits<u32>::max)()); if (Settings::values.serial_unit.GetValue() == 0) Settings::values.serial_unit.SetValue(distribution(gen)); if (Settings::values.serial_battery.GetValue() == 0) Settings::values.serial_battery.SetValue(distribution(gen));

也就是说，不设置时模拟器会随机生成一个u32范围内的数字并持久化到配置中，后续序列号拼装逻辑保持不变。对开发测试而言，显式指定一个固定值能带来可复现的调试环境（同一序列号在多次启动间一致），这对排查与序列号绑定的应用逻辑（如系统设置显示、DRM 相关分支）尤为重要。

建议的调试工作流

综合上述能力，一个典型的 homebrew 调试循环如下：

1. 准备密钥：在keys目录放置目标密钥集（prod.keys或按前缀命名的其他*.keys）；
2. 固定设备身份：在配置文件中设置serial_unit（以及需要时的serial_battery）为非零值，保证每次启动序列号一致；必要时调整region_index以测试不同地区的行为；
3. 选择密钥集：按"标准密钥前缀"功能指向当前要测试的密钥文件，或在调试页切换use_dev_keys（开发/零售密钥）后保存，触发ReloadKeys()重载；
4. 传递参数运行：通过--program/-p（或调试页的 Homebrew Args）向应用传入参数，例如-noglsl；
5. 需要断点时：启用 GDB stub——相关设置见 settings.h 中的use_gdbstub与gdbstub_port（默认6543），并在命令行使用--debug/-d进入调试模式；
6. 回归验证：更多测试层面的说明可参考用户手册的 Testing。

小结

Eglantine 将"原生应用调试"落在两个最小但关键的可控变量上：密钥集前缀决定了用哪一套加密材料运行系统（底层由 key_manager.cpp 的ReloadKeys()实现，覆盖prod/dev/title/console四类密钥），序列号与电池编号决定了设备身份（由 system_settings_server.cpp 中基于serial_unit/serial_battery/region_index的拼装逻辑生成，末位校验自动补全，零值时随机生成）。理解这两条链路后，开发者就能在模拟器中构造出稳定、可复现、接近真实系统环境的 homebrew 测试条件。

需要说明的前提：本仓库处于高度实验阶段（项目描述为 "VERY experimental Nintendo Switch 2 emulator"），上述行为以当前仓库源码为准，密钥文件的具体内容获取方式不在本文讨论范围内。