3dsconv实用指南：把3DS卡带镜像变成可安装CIA，其实只需一条命令

【免费下载链接】3dsconvPython script to convert Nintendo 3DS CCI (".cci", ".3ds") files to the CIA format项目地址: https://gitcode.com/gh_mirrors/3d/3dsconv

周末整理硬盘时，我翻出一堆当年从3DS卡带dump出来的.3ds镜像，想着"存着以后玩"，结果等真把游戏机拿出来，才发现它只认CIA格式。直到我用了3dsconv——一个能把任天堂3DS的CCI镜像（.3ds/.cci）转换成可安装CIA格式的Python工具，这批尘封的游戏才终于能装回机器里。如果你也在为"镜像躺在硬盘里却装不上游戏机"发愁，这篇文章会带你走完从下载工具到批量转换的全过程。

它到底是做什么的：一句话讲清3dsconv的价值

3dsconv是一个纯Python编写的开源工具，MIT协议，作者是ihaveamac。它的工作内容一句话就能说清：读取CCI镜像（也就是.3ds文件），解析内部的NCSD/NCCH结构，把游戏主体、说明书、下载游玩等分区重新打包成一个标准的CIA安装包。

比起社区里其他的转换方案，它有几个让人省心的地方：

• 三种加密状态自动识别，不用你先去猜这个ROM是明文还是加了密
• 密钥文件自动搜索，把boot9.bin放在几个约定位置就能被找到
• 内置哈希校验，转换过程中顺手给你的文件做一次"体检"
• 一条命令可以同时喂进好几个文件，天生支持批量
• 整个核心逻辑集中在一个.py文件里（3dsconv/3dsconv.py），想研究实现或魔改都很轻松

一句话总结它的定位：不折腾、不挑食、开箱即用。

在3dsconv完成首次转换的完整步骤

环境要求非常简单：Python 3.6及以上版本，Windows、macOS、Linux都行。转换未加密的ROM不需要任何额外依赖；只有碰到加密ROM时，才需要补一个AES加密库pyaes。

先克隆代码并安装依赖：

git clone https://gitcode.com/gh_mirrors/3d/3dsconv cd 3dsconv pip install pyaes

接下来挑一个未加密的.3ds文件试水。下面的命令把转换结果统一输出到转换结果目录：

python3 3dsconv/3dsconv.py 我的游戏.3ds --output=./转换结果

预期输出大致长这样：

3dsconv.py ~ version 4.21 Converting 我的游戏 (decrypted)... Writing Game Executable CXI... 100.0% 157286400 / 157286400 Writing Manual CFA... Done converting 1 out of 1 files.

命令行格式就是"脚本 + 输入文件 + 可选参数"。--output=用来指定输出目录，不写的话文件会落在当前目录；转换完成后，输出目录里会出现一个同名.cia文件，拷到SD卡上就能用FBI之类的工具安装了。✅ 到这一步，你的第一次转换已经跑通。

拆开看看：3dsconv最值得掌握的四个核心能力

自动识别三种加密状态，省去手动判断

3DS卡带镜像一共有三种状态：未加密、原始NCCH加密、zerokey加密。用旧工具时你得自己先判断ROM属于哪一种，选错参数就是一堆乱码。而3dsconv在读文件时，会主动去看镜像头部0x18F偏移处的加密标志位，然后自动走对应路线：明文直接打包，zerokey加密用全零密钥处理，原始NCCH加密则用从boot9中提取的密钥来解密。全程不用你插手。

💡 小技巧：如果某个ROM的加密标志被写错了，但你确定它其实是明文，可以加--ignore-encryption强制按未加密处理，工具还会顺手把标志位改成NoCrypto，避免后续环节误判。

自动搜索boot9.bin密钥文件的完整顺序

处理原始NCCH加密的ROM，需要一份ARM9 bootROM，也就是boot9.bin或boot9_prot.bin。这文件要用boot9strap从你自己的3DS上导出（开机时按住START+SELECT+X，就能dump到/boot9strap/目录下）。拿到之后你不用指定路径，工具会按固定顺序自动寻找：

1. 命令行参数--boot9=，或环境变量BOOT9_PATH
2. 当前目录下的boot9.bin（完整版）
3. 当前目录下的boot9_prot.bin（保护版）
4. 用户目录~/.3ds/boot9.bin
5. 用户目录~/.3ds/boot9_prot.bin

💡 小技巧：boot9是敏感文件，拷来拷去容易出错，建议转档前先核对哈希：

sha256sum boot9.bin # 期望输出：2f88744feed717856386400a44bba4b9ca62e76a32c715d4f309c399bf28166f

boot9_prot.bin的正确哈希是7331f7edece3dd33f2ab4bd0b3a5d607229fd19212c10b734cedcaf78c1a7b98，对不上就说明文件有问题。

内置哈希校验，外加两个容错开关

转换过程中，工具会对ExtHeader、游戏分区等内容做SHA-256哈希计算，再和镜像头部记录的值比对。一旦发现对不上，它会停下并提示"This file may be corrupt"，而不是闷头产出一个坏文件。这个设计在镜像经过多次拷贝、转储后特别有用。

💡 小技巧：如果镜像本身没问题，只是头部记录的哈希有偏差，可以加--ignore-bad-hashes强制继续；如果文件真的损坏了，想强行抢救一下，兜底的也是同一个参数。

用--dev-keys处理开发者密钥游戏

如果手里是开发机（dev-unit）的镜像，加密用的是开发密钥，需要加--dev-keys切换到对应的密钥体系。此时工具会去当前目录或~/.3ds/下寻找certchain-dev.bin证书链。要注意的是，转换结果仍然是开发密钥加密的，只能在开发机上安装，这一步只是让打包过程能匹配正确的密钥体系。

进阶玩法：如何用3dsconv批量转换与脚本化

单文件转换只是开胃菜。3dsconv天然支持一次传入多个文件，空格分隔即可：

python3 3dsconv/3dsconv.py 游戏1.3ds 游戏2.3ds 游戏3.cci --output=./cia输出

配合shell通配符，整个目录一次性搞定：

python3 3dsconv/3dsconv.py ./roms/*.3ds --output=./cia输出 --overwrite

这里--overwrite的作用是允许覆盖已存在的.cia文件——默认情况下工具发现输出重名会直接拒绝，这是为了防止误覆盖，而不是bug。🚀

经常处理加密ROM的话，还可以把boot9路径写进环境变量，省得每次敲参数：

export BOOT9_PATH=/path/to/boot9.bin

Windows用户还有更省事的玩法：用py2exe把脚本打包成3dsconv.exe，之后直接把.3ds文件拖到exe图标上就能完成转换，完全不用记命令行。

新手避坑：5个高频报错问答

Q1：报错"pyaes not found, encryption will not be supported"

• 现象：工具能启动，但一碰到加密ROM就罢工。
• 原因：没装pyaes这个加密库。
• 解决：执行pip install pyaes后重试。

Q2：报错"bootROM not found, encryption will not be supported"

• 现象：加密ROM转换失败。
• 原因：工具找不到boot9.bin，提取不出密钥。
• 解决：把boot9.bin（或boot9_prot.bin）放到当前目录或~/.3ds/下，或者用--boot9=/完整/路径显式指定。

Q3：提示"xxx.cia already exists"

• 现象：转换还没开始就被拦下了。
• 原因：输出目录已有同名文件，工具默认不覆盖。
• 解决：加--overwrite参数。

Q4：报错"is not a CCI file (missing NCSD magic)"

• 现象：文件被直接拒绝。
• 原因：喂进去的不是卡带镜像，比如3DS的NAND备份虽然也带NCSD头，但缺少NCCH标志，会被判定为无效输入。
• 解决：确认输入是完整的.3ds/.cci卡带镜像，而不是其他格式的dump产物。

Q5：提示"This file may be corrupt (invalid ExtHeader hash)"

• 现象：哈希校验不通过，转换中断。⚠️
• 原因：要么文件真的损坏，要么加密状态判断错误导致校验对不上。
• 解决：确认ROM是明文的话加--ignore-encryption；文件确实坏了但想强行转换就加--ignore-bad-hashes。

把3dsconv用起来：下一步行动清单

3dsconv解决的是一个非常具体的问题：让躺在硬盘角落里的.3ds镜像，重新变成能装回3DS的CIA文件。它没有花哨的界面，也没有复杂的配置，一条命令就把事情办完——这种"工具就该这样简单"的气质，正是它最讨人喜欢的地方。

如果你也收藏着成堆的3DS镜像，现在就可以动手：克隆仓库、装上pyaes、拿一个明文ROM跑通第一次转换，再逐步解锁加密、批量、自动化的全部姿势。用着顺手，就去仓库点个Star；遇到问题，把使用场景和报错信息整理好提个Issue；想学习一个纯Python工具怎么实现AES-CTR解密、NCCH解析和CIA拼装，这份源代码本身就是很好的教材。剩下的路，交给你的游戏库去填满吧。

【免费下载链接】3dsconvPython script to convert Nintendo 3DS CCI (".cci", ".3ds") files to the CIA format项目地址: https://gitcode.com/gh_mirrors/3d/3dsconv