3dsconv 使用教程一个 Python 脚本把 3DS 卡带镜像转成 CIA 安装包【免费下载链接】3dsconvPython script to convert Nintendo 3DS CCI (.cci, .3ds) files to the CIA format项目地址: https://gitcode.com/gh_mirrors/3d/3dsconv3dsconv 是一款用 Python 3 编写的开源小工具能把任天堂 3DS 的卡带镜像文件.3ds / .cci一键转换成可以直接安装的 CIA 格式。本文从一个真实场景出发带你从零跑通第一次转换讲透加密检测、boot9.bin 配置和常见报错新手也能在 10 分钟内上手。从一堆装不进去的 3DS 镜像说起想象这样一个下午你翻出一个落灰的旧硬盘里面整整齐齐躺着十几个.3ds文件——那是你早年用自制软件备份的 3DS 卡带镜像。你兴冲冲地把它们拷到 SD 卡上准备装回主机重温结果开机发现根本装不了。这不是你的操作问题而是格式问题。3DS 主机能识别的安装包是 CIA 格式CTR Importable Archive可以理解为任天堂的数字安装包而卡带备份出来的镜像叫 CCICTR Cart Image卡带原始镜像扩展名通常是.3ds或.cci。两者结构完全不同中间还隔着一道加密的坎。这就是3dsconv存在的理由一个命令行脚本把 CCI 转成 CIA顺便帮你处理加密问题。先搞清楚它到底做了什么3dsconv由开发者 ihaveamac 编写以 MIT 许可证开源整个项目只有一个核心文件3dsconv/3dsconv.py加一个依赖库pyaes。它的定位非常纯粹输入.3ds/.cci文件输出可安装的.cia文件。第一次接触 3DS 格式的人可能会被一堆缩写吓到其实只需要记住这几件事缩写全称人话版在转换中的作用CCI卡带镜像文件.3ds/.cci转换的输入CIA数字安装包格式转换的输出装进 3DS 用NCSD卡带镜像的外层容器脚本靠它识别这是个 CCINCCH容器里的加密分区游戏本体就装在里面也是加密/解密的主战场一个诚实的提醒3dsconv的作者在 README 里自己也说了新版的 GodMode9、Decrypt9WIP 已经支持直接把卡带转储成 CIA所以这个工具部分过时了。但如果你手里有现成的 .3ds 旧镜像或者不想折腾自制系统的转储流程它依然是最省事的批量转换方案。这正是它的价值所在。第一次上手三步跑通首个转换第一步拉代码 装依赖git clone https://gitcode.com/gh_mirrors/3d/3dsconv cd 3dsconv pip install pyaespyaes是纯 Python 实现的 AES 加密库负责解密环节。注意如果你要转换的镜像本来就是未加密的甚至可以跳过这一步但建议还是装上以防遇到加密镜像时抓瞎。第二步确认工具能用不跟任何参数直接运行脚本它会打印版本号和完整的帮助信息python3 3dsconv/3dsconv.py正常的话你会看到类似这样的输出3dsconv.py ~ version 4.21 Convert Nintendo 3DS CCI (.3ds/.cci) to CIA Usage: 3dsconv.py [options] game [game...] Options: --outputdir - Save converted files in specified directory --boot9file - Path to dump of ARM9 bootROM, protected or full --overwrite - Overwrite existing converted files ...看到帮助信息说明环境没问题。第三步转换第一个文件python3 3dsconv/3dsconv.py my_game.3ds --outputcia_files/这里有两个容易踩的细节先记住--output后面跟的是目录不是文件名。转换结果会以原文件名 .cia的形式保存在这个目录里目录不存在会自动创建。必须写成--output目录这种带等号的写法。如果你写成--output 目录或-o 目录脚本会把它当成不存在的输入文件直接报错后面翻车现场还会提到。转换过程中会实时刷新一个进度条百分比 字节数结束后打印一句总结Done converting 1 out of 1 files.如果一次有多个文件直接并列写就行还支持通配符批量匹配# 逐个列出 python3 3dsconv/3dsconv.py game1.3ds game2.3ds game3.3ds --outputcia_files/ # 或者用通配符一次扫完 python3 3dsconv/3dsconv.py *.3ds --outputcia_files/看到这里你已经完成了 90% 的日常使用。剩下需要关心的就是加密这件事。它凭什么能转换加密镜像3DS 的卡带镜像有三种状态3dsconv会自动识别不需要你手动判断未加密decrypted最常见于 GodMode9 等工具转储后的文件直接转换零依赖。zerokey 加密用的是一把全零密钥3dsconv内置处理同样不需要外部密钥文件。Original NCCH 加密slot 0x2C零售卡带的标准加密需要一把特殊的密钥而这把密钥藏在 3DS 主机的 ARM9 bootROM 里。检测逻辑在源码里其实很短大致是这样的示意代码非完整实现# 读取加密标志位 rom.seek(game_cxi_offset 0x18F) encryption_bitmask rom.read(1)[0] encrypted not (encryption_bitmask 0x4) zerokey_encrypted encryption_bitmask 0x1 if zerokey_encrypted: # 用全零密钥解密 key zerokey elif encrypted: # 用从 boot9 里提取的密钥 NCCH keyY 计算最终密钥 key rol((rol(orig_ncch_key, 2, 128) ^ key_y) 0x1FF9..., 87, 128)所以处理加密镜像时真正的问题是去哪找 boot9.bin3dsconv会按照固定顺序自动查找找到即用查找顺序路径说明1--boot9参数指定的路径最高优先级2当前目录下的boot9.bin完整版 bootROM3当前目录下的boot9_prot.bin保护版 bootROM4~/.3ds/boot9.bin用户目录下的完整版5~/.3ds/boot9_prot.bin用户目录下的保护版boot9 是 3DS 自制系统用户才有的东西安装 boot9strap 后开机按住STARTSELECTX就能在sdmc:/boot9strap/下导出。拿到文件后可以用 SHA256 校验一下是否完整完整版boot9.bin的 SHA256 为2f88744feed717856386400a44bba4b9ca62e76a32c715d4f309c399bf28166f保护版boot9_prot.bin为7331f7edece3dd33f2ab4bd0b3a5d607229fd19212c10b734cedcaf78c1a7b98。除了解密3dsconv在转换过程中还默默做了三件小事哈希校验逐块计算 SHA-256并和镜像里的原始哈希比对发现不一致会警告文件可能损坏。ExtHeader 补丁把可执行分区的扩展头打上补丁让输出的 CIA 能被安装流程正常接受。图标提取从 ExeFS 里把游戏的 SMDH 图标挖出来写进 CIA 的 meta 区域安装后能在主机菜单里看到正确的图标和标题。进阶玩法参数、环境变量与开发者模式除了--output3dsconv还提供了一批实用参数全部在帮助信息里可见参数作用--boot9file手动指定 boot9 文件路径优先级最高--overwrite强制覆盖已存在的同名 CIA--ignore-bad-hashes哈希校验失败也继续转换慎用--ignore-encryption忽略加密标志位按未加密处理仅在你确定镜像实际未加密时使用--verbose打印详细信息Title ID、各分区大小、密钥校验结果、各类哈希值--dev-keys使用开发者主机dev-unit的密钥体系两个进阶用法值得单独说1. 环境变量 BOOT9_PATH如果你不想每次敲--boot9可以把路径写进环境变量export BOOT9_PATH/path/to/your/boot9.bin之后运行脚本时会自动读取优先级介于--boot9和当前目录查找之间。同理把 boot9 放在~/.3ds/下也能被自动找到一劳永逸。2. 开发者版本游戏--dev-keys某些用开发者密钥加密的标题README 提到主要见于 SystemUpdater需要用--dev-keys配合开发者证书链转换python3 3dsconv/3dsconv.py dev_game.3ds --dev-keys脚本会按当前目录 →~/.3ds/的顺序查找certchain-dev.bin找不到就报错退出。需要提醒的是--dev-keys并不会改变输出的加密状态转出来的 CIA 依然只能用开发机安装不是给零售主机用的。如果你有开发者版 CIA可以用ctrtool --certscertchain-dev.bin title.cia把它里面的证书链提取出来。新手最容易踩的 5 个坑把这些报错背下来你基本就不会卡壳了坑 1加密相关功能全部失灵Error: pyaes not found, encryption will not be supported Error: bootROM not found, encryption will not be supported前者说明没装pyaespip install pyaes后者说明没找到 boot9 文件。未加密镜像不受影响加密镜像必须补齐这两样。坑 2文件名或参数写错Error: game.3ds doesnt exist. Error: -o doesnt exist.注意第二行的诡异报错——-o被当成文件了。记住3dsconv只认--output目录这种带等号的写法不支持-o短参数。另外参数里如果带了通配符比如*.3ds在 shell 里最好加引号避免被提前展开成不存在的路径。坑 3同名文件被拒绝Error: game.cia already exists. Use --overwrite to force conversion.输出目录里已有同名 CIA 时默认跳过防止误覆盖。确认没问题就加--overwrite。坑 4文件根本不是 CCIError: xxx.bin is not a CCI file (missing NCSD magic).脚本会先检查文件头 0x100 处的NCSD魔数、再检查游戏分区里的NCCH魔数——连 3DS 的 NAND 备份同样带 NCSD 头都会被这道检查拦下来避免误转换。报这个错说明你拿错了文件。坑 5哈希校验失败警告This file may be corrupt (invalid ExtHeader hash). If you are certain that the rom is decrypted, use --ignore-encryption这通常意味着镜像本身是未加密的但头部标志位仍然写着已加密导致解密出来的数据对不上哈希。如果你能确认文件来源可靠用--ignore-encryption或--ignore-bad-hashes放行即可如果文件是别人传的先重新转储一次更稳妥。收尾合规提醒与延伸阅读最后说几句掏心窝的话。关于合规请只转换你合法拥有的游戏备份转换前后保留好原始文件不要做任何形式的传播分发。3dsconv本身是 MIT 开源项目工具无罪但怎么用是每个人的选择。关于原理想深入研究的同学整个转换逻辑都集中在 3dsconv/3dsconv.py 这一个文件里代码风格相当直白。你可以顺着几条主线去读开头是证书链和 ticket/tmd 的 base64 数据、中间是 NCSD/NCCH 头部解析与密钥计算用到了rol循环移位、后面是分区数据流式写出与三类 SHA-256 哈希的逐段更新。读懂它你对 3DS 文件格式的理解会上一个台阶。关于未来由于 GodMode9 已经能直接产出 CIA3dsconv的主要用武之地是存量镜像的批量化转换。但反过来看也正是因为这种小工具的存在才让很多玩家手里的旧备份重新变得可用。现在去把你的第一个.3ds文件拖进命令行试试吧。顺利的话一杯咖啡的功夫CIA 就能装进你的 3DS 了。【免费下载链接】3dsconvPython script to convert Nintendo 3DS CCI (.cci, .3ds) files to the CIA format项目地址: https://gitcode.com/gh_mirrors/3d/3dsconv创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考