3dsconv 保姆级教程：5 分钟把 .3ds 游戏转为可安装的 CIA 格式

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

你有没有经历过这样的时刻：费了半天劲把 3DS 卡带转储成了.3ds文件，兴冲冲准备装回主机，结果发现 3DS 根本不认这种格式，只能干瞪眼。更麻烦的是，转储出来的文件还分"加密"和"未加密"，普通玩家根本分不清，更别提自己写脚本解密了。

这就是 3dsconv 要解决的问题。它是一个开源的 Python 3 小工具，专门把 Nintendo 3DS 的 CCI（卡带镜像，扩展名通常是.3ds或.cci）转换成 CIA 安装包格式，并且能自动识别文件的加密状态。今天这篇教程就带你从零上手，把"转储 → 转换 → 安装"这条链路一次走通。

先扫盲：CCI 和 CIA 到底差在哪

在动手之前，我们花两分钟把两个术语说清楚，后面才不会一头雾水：

• CCI（.3ds / .cci）：CTR Cart Image 的缩写，是 3DS 卡带内容的"原始镜像"，相当于把整张卡带逐字节复制出来的文件。它只能被模拟器读取或做研究用，不能直接安装到主机。
• CIA（.cia）：CTR Importable Archive 的缩写，可以理解成 3DS 专用的"安装包"。把它放到 SD 卡里，用 FBI 之类的自制安装器点一下，游戏就装进主机的虚拟系统里了。

简单说：CCI 是"源文件"，CIA 是"安装包"。3dsconv 干的就是中间的转换活，而且它会帮你判断文件是未加密、NCCH 加密还是 zerokey 加密，再选对路子处理——这一步正是它最省心的地方。

为什么选它：四个让人记住的点

• 加密状态全自动识别：文件头里的加密标志位、NCCH 分区状态它都会自己读，你不需要手动指定"我这个文件是哪种加密"。对普通用户来说，意味着"扔进去就能跑"。
• SHA-256 全程保驾护航：转换过程中会实时计算哈希值并写进 CIA，同时校验源文件的 ExtHeader 哈希。文件如果损坏了，它会明明白白告诉你，而不是闷头给你产出一个坏包。
• 批量与通配符支持：一次可以传多个文件，还支持*.3ds这种通配写法，整理几十上百个游戏也只需一行命令。
• 跨平台、零依赖负担：纯 Python 3 实现，除了解密用到的pyaes库外没有其他强制依赖，Windows、macOS、Linux 都能跑。

另外提一句诚实的话：README 里作者也说明了，现在 Decrypt9WIP 和 GodMode9 可以直接把卡带转储成 CIA，3dsconv 的定位更多是处理你手里已经存在的 .3ds 老转储文件。如果你手头正堆着这么一堆文件，它依然是最顺手的工具。

动手前准备：装好 Python 和 pyaes

3dsconv 是一个命令行脚本，不需要图形界面，但它需要两样东西：Python 3 环境和加密库 pyaes。

打开终端，先确认 Python 版本：

python3 --version

只要显示的是 Python 3.x（3.6 以上即可）就满足要求。然后安装解密必需的依赖库：

pip install pyaes

pyaes 是一个纯 Python 实现的 AES 加密库，体积很小。如果后续转换加密文件时报"pyaes not found"，就是这一步没做好的信号。

第一次转换：从克隆到跑通

把项目拿到本地，然后直接运行脚本，不需要安装也能用：

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

最基本的转换命令只写文件名就够了：

python3 3dsconv.py game.3ds

脚本会先打印版本号，然后显示类似下面的信息：

3dsconv.py ~ version 4.21 Converting game (decrypted)... Writing Game Executable CXI... 100.0% ... Done converting 1 out of 1 files.

转换完成后，当前目录下会多出一个game.cia文件——输出文件与源文件同名，只是扩展名从.3ds变成了.cia。如果你觉得每次都输python3 3dsconv.py太长，也可以执行python3 setup.py install安装，之后就能用3dsconv短命令调用了。

在 Windows 上还有个更偷懒的办法：如果你用的是打包好的3dsconv.exe版本，直接把.3ds文件拖到 exe 图标上松手，就能完成转换。

加密文件怎么办：boot9.bin 的前因后果

如果你只转未加密的游戏，上面那步就结束了。但现实中不少.3ds转储是加密的，这时 3dsconv 需要一把"钥匙"才能解密——这把钥匙藏在一个叫boot9的文件里。

boot9 是什么，从哪来

boot9 是 3DS 主机的 ARM9 启动 ROM 转储，相当于主机固件的一部分。它需要用boot9strap（一套自制引导工具）从你自己的 3DS 上提取：按 3DS Guide 完成 boot9strap 安装后，开机时按住START + SELECT + X，它就会把文件转储到 SD 卡上的sdmc:/boot9strap/boot9.bin。

提取出来的文件可能是两个版本之一：

• boot9.bin：完整版，SHA-256 校验值为2f88744feed717856386400a44bba4b9ca62e76a32c715d4f309c399bf28166f
• boot9_prot.bin：保护版，SHA-256 校验值为7331f7edece3dd33f2ab4bd0b3a5d607229fd19212c10b734cedcaf78c1a7b98

建议转储后用sha256sum核对一下哈希，确认文件完好再使用。

自动查找顺序：你几乎不用手动指定路径

拿到 boot9 文件后，把它放到项目目录（或~/.3ds/目录）里，3dsconv 启动时会按这个顺序自动寻找：

1. 命令行参数--boot9=<文件路径>指定的位置
2. 当前目录下的boot9.bin
3. 当前目录下的boot9_prot.bin
4. 用户主目录下的~/.3ds/boot9.bin
5. 用户主目录下的~/.3ds/boot9_prot.bin

也就是说，最省事的做法是把boot9.bin丢进当前目录，然后照常运行转换命令：

python3 3dsconv.py encrypted_game.3ds

文件会被识别为encrypted状态并自动解密转换。如果找不到 boot9，脚本会明确提示bootROM not found, encryption will not be supported，这时候转换加密文件就会直接报错跳过。

六个参数，逐个拆给你看

--output=<目录>：指定输出目录，不写就存到当前目录。

python3 3dsconv.py game.3ds --output=./cia_files

--overwrite：默认情况下，如果同名.cia已存在，脚本会拒绝转换并报错。加上这个参数则强制覆盖。

--ignore-encryption：忽略文件头里的加密标志，把文件当作未加密处理。适用于你确定文件其实是明文、但标志位被改过的场合，滥用它转换真正的加密文件只会得到坏结果。

--ignore-bad-hashes：遇到哈希校验不过的文件时，不中断而继续转换。通常配合--verbose先看清问题再决定是否使用。

--verbose：打印更详细的过程信息，包括 Title ID、各分区大小、每步的 SHA-256 哈希等。排查问题时非常好用。

--dev-keys：使用开发者主机（开发机）的密钥体系，专门处理开发机加密的标题，这个留到进阶部分细说。

多个参数可以组合使用，比如：

python3 3dsconv.py game.3ds --output=./out --verbose

实战场景：整库批量转换

手里有几十个.3ds文件要整理？一个 for 循环就能搞定。下面这个脚本会把games目录里所有.3ds文件转成 CIA，输出到cia_files目录：

#!/bin/bash input_dir="./games" output_dir="./cia_files" mkdir -p "$output_dir" for file in "$input_dir"/*.3ds; do if [ -f "$file" ]; then echo "正在转换: $(basename "$file")" python3 3dsconv.py "$file" --output="$output_dir" fi done echo "批量转换完成！"

转换过程中你会看到进度条实时刷新百分比和字节数，即使是大文件（动辄 1~2GB）也能心里有数。如果中途断电或异常退出，重跑一遍加上--overwrite即可，之前的成果不会丢失。

进阶：开发者密钥与 certchain

如果你需要处理开发机（dev-unit）的标题，情况会复杂一些。开发机的加密用的是开发者密钥，必须同时满足两个条件：

1. 命令加上--dev-keys参数，同时脚本需要找到certchain-dev.bin（开发者证书链）。它会按"当前目录 →~/.3ds/"的顺序查找，该文件的 SHA-256 校验值为7921ae82c9dcf411351314f2fe2c67378c6a872d2524f71b3c002b4d4a56846f。
2. 证书链需要你从已有的开发版 CIA 中提取，用到的命令是：

ctrtool --certs=certchain-dev.bin title.cia

需要提醒的是，--dev-keys模式不会改变输出文件的加密方式，转换出来的 CIA 仍然是开发密钥加密的，只能在开发机上安装。README 里也标注了这一功能"未经完整测试"，普通玩家基本用不上，这里只是让你知道有这回事。

常见报错排查（FAQ）

报错 "bootROM not found, encryption will not be supported"可能原因：没安装 pyaes，或没找到 boot9 文件。解决方案：先执行pip install pyaes，再把boot9.bin/boot9_prot.bin放到当前目录或~/.3ds/下，或者直接用--boot9=/绝对路径/boot9.bin指定。

报错 "xxx is not a CCI file (missing NCSD magic)"可能原因：文件不是合法的.3ds镜像，或者拿错了文件（比如 3DS 的 NAND 转储虽然也有 NCSD 标志，但脚本会通过 NCCH 校验进一步拦截）。解决方案：确认源文件是卡带转储，重新转储后再试。

提示 "This file may be corrupt (invalid ExtHeader hash)"可能原因：文件被修改过、转储不完整，或者文件本身已解密但标志位没改。解决方案：如果你确定文件是明文，先试试--ignore-encryption；如果确实是坏文件，再考虑用--ignore-bad-hashes强制转换。

报错 "game.cia already exists. Use --overwrite to force conversion"可能原因：同名文件已存在。解决方案：加上--overwrite，或者换个--output目录。

关于安全与合规，务必记住这几点

3dsconv 这类工具天然和破解生态相关，使用时有几条底线要守住：

• 只转换你合法拥有的游戏：无论是自己买的卡带转储，还是官方渠道获得的文件，转换本身没问题；盗版文件无论用什么工具处理都是不合规的。
• boot9 只应从你自己的机器提取：它属于主机固件，来源不明、哈希对不上的文件可能是被篡改过的，别乱用。
• 转换结果仅限个人使用：不要传播、不要商用，这也是对所有游戏开发者劳动的基本尊重。

另外在操作层面，建议转换前先备份原始.3ds文件、转储后用sha256sum核对 boot9 哈希、批量转换时保留终端日志方便回溯——这些习惯能帮你省掉很多返工。

现在就可以开始

回看整条路径，其实非常简单：装 pyaes → 克隆仓库 → 准备 boot9 → 运行脚本。把下面这段命令存成你的备忘录：

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

转换完成后，把生成的.cia放进 SD 卡，用 FBI 安装即可。下一次当你再次面对一抽屉的.3ds老文件时，你已经知道该怎么处理它们了。打开终端，跑起你的第一行命令吧——五分钟之后，你就能在 3DS 上看到熟悉的游戏图标了。

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