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 自制系统时，都会卡在同一个环节：手里明明有一堆.3ds格式的游戏镜像，FBI 却只认.cia文件，装不上、玩不了，急得直挠头。手动找转换工具、研究命令行参数、还要搞懂什么是加密分区……光是准备工作就劝退了大半新手。今天要聊的3dsconv，就是用来解决这个"最后一公里"问题的。

先从一个让人抓狂的场景说起

想象一下这个画面：你在网上找到一款心仪游戏的.3ds镜像，兴冲冲拷进 SD 卡，打开 FBI 准备安装，结果界面提示"文件格式不支持"。你再查资料，发现 3DS 的 CIA 安装格式和卡带镜像.3ds（也叫 CCI）完全是两码事——前者是数字版安装包，后者是卡带 ROM 的完整镜像，虽然内容几乎一样，但结构上就差一层"包装"。

更麻烦的是，很多游戏镜像还是加密的。普通加密倒还好，如果遇到 zerokey 加密或者需要 ARM9 bootROM 才能解密的原始 NCCH 加密，没有合适的工具和密钥文件，转换过程会直接报错。这时候你就需要一把"瑞士军刀"——3dsconv就是干这个的。

一句话认识它

3dsconv是一个用 Python 3 写的命令行工具，专门把任天堂 3DS 的 CCI 文件（扩展名为.3ds或.cci）转换成可直接用 FBI 安装的 CIA 格式。它适合所有想把手头游戏备份转成可安装格式的玩家，也适合自制软件开发者做打包前的格式准备。你不需要懂加密原理，只要会敲一两行命令就够了。

三步极速上手：先把第一个文件转出来

咱们不整虚的，直接从"能跑起来"开始。

第一步：拿到代码并安装依赖

# 克隆项目仓库 git clone https://gitcode.com/gh_mirrors/3d/3dsconv # 进入项目目录 cd 3dsconv # 安装加密依赖 pyaes（只有加密游戏需要，但建议直接装好） pip install pyaes

第二步：执行一次最小转换

# 把当前目录下的 game.3ds 转成 game.cia python3 3dsconv/3dsconv.py game.3ds

就是这么简单，转换结果默认输出到当前目录，文件名和输入文件同名，只是扩展名变成.cia。运行时会显示实时进度条，转完会打印类似Done converting 1 out of 1 files.的汇总信息。

第三步：验证是否安装成功

什么都不带直接运行脚本，就能看到它的完整用法说明，这是最快的"自检"方式：

python3 3dsconv/3dsconv.py

看到输出里有3dsconv.py ~ version 4.21和完整的选项列表，说明环境一切正常，可以正式开始使用了。

一张表看懂它能做什么

上手之后，先建立整体认知。下面这张表帮你快速了解 3dsconv 的核心能力和适用场景：

还有一个加分项：3dsconv是 MIT 协议的开源项目，代码完全开放，你可以自由使用、学习甚至改造它。

高频场景实战：照着抄就能用

接下来挑几个最常用的场景，每个都给可直接复制的命令。

场景一：批量转换整个文件夹

手里有几十个游戏镜像，一个个转换太折磨人。3dsconv 原生支持多文件输入，配合通配符一次搞定：

# 转换当前目录下所有 .3ds 文件，结果统一放进 cia_files 目录 python3 3dsconv/3dsconv.py *.3ds --output=cia_files/ # 也可以显式列出多个文件 python3 3dsconv/3dsconv.py game1.3ds game2.3ds game3.3ds --output=cia_files/

注意--output=后面接的是输出目录，不是文件名，输出文件名会自动沿用输入文件名。如果目标目录不存在，工具会自动创建。

场景二：转换加密游戏（需要 boot9.bin）

遇到加密镜像时，工具会按以下顺序自动查找密钥文件：

1. --boot9=参数指定的路径
2. 当前目录下的boot9.bin
3. 当前目录下的boot9_prot.bin
4. ~/.3ds/boot9.bin
5. ~/.3ds/boot9_prot.bin

建议把 boot9 文件提前放到~/.3ds/目录，之后转换加密游戏就不用每次指定路径了。也可以手动指定：

# 手动指定 boot9.bin 路径，转换加密游戏 python3 3dsconv/3dsconv.py encrypted_game.3ds --boot9=/path/to/boot9.bin

关于 boot9.bin 从哪来：在已安装 boot9strap 的 3DS 主机上，开机时按住START + SELECT + X，会把你主机的 boot9 导出到sdmc:/boot9strap/boot9.bin，拷贝到电脑上即可。拿到文件后可以用下面的哈希值核验文件完整性：

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

场景三：转换被判定为损坏的镜像

如果你的镜像本身没问题，但转换时反复报哈希错误，大概率是加密状态判断出了问题。此时可以用两个"信任模式"参数强制转换：

# 跳过哈希校验，强行转换 python3 3dsconv/3dsconv.py game.3ds --ignore-bad-hashes # 明确告知工具"这个文件是未加密的"，忽略加密头信息 python3 3dsconv/3dsconv.py game.3ds --ignore-encryption

这两个参数本质上是"跳过安全检查"，仅建议在确定文件来源可靠时使用，转换前最好保留原始镜像备份。

场景四：开发者版本游戏转换

如果你手上的是开发者单元（dev-unit）专用游戏，普通零售密钥解不开，需要启用开发者密钥模式：

# 启用开发者密钥模式 python3 3dsconv/3dsconv.py dev_game.3ds --dev-keys

这个模式要求当前目录（或~/.3ds/）下存在certchain-dev.bin文件，它是开发机的证书链，可以借助ctrtool从开发版 CIA 中提取：

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

要提醒的是：--dev-keys转换出的 CIA 仍然使用开发机密钥加密，只能在开发者单元上安装，想装到零售机上还需要额外的解密步骤。

把重复劳动交给脚本：批处理思路

--overwrite参数配合脚本，可以把手动转换变成"一键完成"。先看看这个参数的作用：默认情况下，如果输出文件已存在，工具会报错跳过；加上--overwrite才会强制重新转换。这在重跑批量任务时非常关键。

下面是一个带进度日志的批处理脚本思路，你可以根据自己的目录结构调整：

#!/bin/bash # batch_convert.sh - 批量转换脚本 INPUT_DIR="./games" OUTPUT_DIR="./converted_cia" LOG_FILE="./conversion.log" mkdir -p "$OUTPUT_DIR" echo "开始批量转换: $(date '+%Y-%m-%d %H:%M:%S')" | tee -a "$LOG_FILE" python3 3dsconv/3dsconv.py "$INPUT_DIR"/*.3ds \ --output="$OUTPUT_DIR" \ --overwrite \ --verbose >> "$LOG_FILE" 2>&1 echo "转换结束: $(date '+%Y-%m-%d %H:%M:%S')" | tee -a "$LOG_FILE"

如果你偏爱环境变量而不是命令行参数，3dsconv 也支持：

# 设置 boot9.bin 的默认路径 export BOOT9_PATH="/path/to/your/boot9.bin" # 设置默认输出目录（对应脚本里的 output-directory 变量） export output-directory="/path/to/output/cia_files"

环境变量设置后，不带参数直接运行脚本就能生效，很适合放进 shell 配置里长期使用。

避坑手册：常见报错对症下药

下面按"症状 → 原因 → 对策"整理最常见的几类问题。

症状一：提示 pyaes not found

症状：

Error: pyaes not found, encryption will not be supported

原因：没装加密依赖库，遇到加密游戏会无法转换。

对策：安装依赖即可，未加密的镜像不受影响：

pip install pyaes

症状二：提示 bootROM not found

症状：

Error: bootROM not found, encryption will not be supported

原因：使用原始 NCCH 加密的游戏需要 boot9.bin（或 boot9_prot.bin）提取密钥，工具没找到。

对策：

1. 用--boot9=显式指定 boot9.bin 路径
2. 或把文件放到~/.3ds/目录让工具自动发现
3. 用上面提到的 SHA256 值核验文件是否完整、未损坏

症状三：提示 "xxx" already exists

症状：

Error: "game.cia" already exists. Use `--overwrite' to force conversion.

原因：输出目录里已有同名 CIA 文件，工具默认不覆盖，避免误操作。

对策：确认想重新转换后，加上--overwrite参数。

症状四：提示 is not a CCI file

症状：

Error: "xxx.3ds" is not a CCI file (missing NCSD magic).

原因：文件头缺少 NCSD/NCCH 标识，说明输入文件不是合法的 CCI 镜像——可能是 3DS 的 NAND 备份、改了扩展名的其他文件，或下载不完整。

对策：确认文件来源，重新下载完整镜像后再试。

症状五：转换后 CIA 无法安装

原因排查：这类问题通常不在转换环节，而是出在后续：

• 重新转换并用--verbose查看详细日志，确认没有哈希告警
• 核对游戏区域与 3DS 主机区域是否一致
• 确认系统版本支持该游戏
• 安装工具（如 FBI）的签名相关功能是否配置正确

和 3DS 自制生态协作：一条完整工作流

3dsconv 不是孤岛，它恰好处于 3DS 自制软件工作流的中段。把它和上下游工具串起来，就是一条从"卡带"到"可玩游戏"的完整流水线：

# 完整工作流示意 # 1. 在 3DS 上用 GodMode9 把卡带转储为 .3ds 镜像 # (GodMode9 -> 卡带选项 -> 转储为 .3ds) # 2. 用 3dsconv 把镜像转成 CIA python3 3dsconv/3dsconv.py "dumped_game.3ds" --output=./cia_files # 3. （可选）用 ctrtool 验证 CIA 内容结构 # ctrtool --contents=contents.txt "game.cia" # 4. 拷贝到 SD 卡，用 FBI 安装到 3DS

值得说明的是，3dsconv 的作者在 README 里也指出：现在 GodMode9、Decrypt9WIP 等工具已经能直接输出 CIA，理论上 3dsconv 的角色被部分取代。但它对"已有镜像"的处理依然不可替代——如果你手里存了一大批早年转储的.3ds文件，3dsconv 仍然是把它们统一转成 CIA 的最快路径，这也是它至今被广泛使用的原因。

写在最后

一句话总结：3dsconv 是 3DS 玩家把旧镜像转成可安装 CIA 的最省心方案——一条命令、自动识别加密、天然支持批量，配合 boot9.bin 就能解决绝大多数转换需求。

作为 MIT 开源项目，它也欢迎社区参与：

• 报告问题：转换失败或行为异常时，带上完整报错日志提交 Issue
• 提交建议：对命令参数、输出格式有想法，可以直接提需求
• 贡献代码：修复 bug、优化转换逻辑，提交 Pull Request
• 完善文档：帮助把使用说明写得更清楚，惠及更多新手

工具的价值在于被好好使用。现在，去把你积压的游戏镜像转出来吧，祝安装顺利，玩得开心！🎮

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