Export_QQDB_CustomFace

QQ 旧版（经典版 9.x）自定义表情库 CustomFace.db 导出工具

把旧版 QQ（如 v9.4.9.27849）用户数据目录里的自定义表情（自定义表情包）按 QQ 原有分组（分类）批量导出为图片文件。

功能特性

• 直接解析旧版 QQ 数据目录中的 CustomFace.db（OLE2 复合文档格式），无需登录 QQ
• 按 QQ 原有分组（分类）导出全部自定义表情图片（GIF / JPG / PNG），自动跳过 fix.bmp 缩略图
• 支持：查看分组清单、导出单个分组、导出多个分组、按 QQ 分组顺序全量导出
• 带图片魔数校验，自动跳过损坏/无法识别的数据
• 纯 Python 标准库实现，无任何第三方依赖，Windows / Linux / macOS 通用
• 数据目录、输出目录全部命令行自定义，无写死的用户路径

文件格式背景

旧版 QQ 把自定义表情存放在用户数据目录（如 ...\88854321\）的两个文件里：

文件	格式	内容
CustomFace.db	OLE2 复合文档	表情本体。顶层每个数字命名的 Storage（1、2、3、5、8、11、15、25、8213…）就是一个表情分组；每个表情由两个 Stream 组成：<md5>.gif/.jpg/.png（原图）和 <md5>fix.bmp（缩略图）
CustomFace.dbc	OLE2 复合文档	元数据。内含 Face2.dat（表情元数据，UTF-16LE 字符串按字节 XOR 单字节密钥混淆；字段如 strId、strFileorg、dwGroupId、strFilePicMd5、strTip；分组名称 strGroupName 为 TEA 加密）、Config.dat、MTRoam.dat 等

说明：分组名称在 Face2.dat 中为 TEA 加密（密钥未知），脚本暂以 Group_<ID> 命名输出文件夹，你可自行重命名。分组 ID 8213 是 QQ 的默认收藏分组。

⚠️ 已知限制（重要）

• 部分图片的分组可能出现错乱，这与直接用 DB 文件恢复/加载表情时的表现一致。原因是 CustomFace.db（OLE2 Storage 结构）与 CustomFace.dbc（Face2.dat 元数据）中的分组归属信息可能不完全一致，且分组名称 TEA 加密无法还原。
• 因此本项目定位为备选方案：适合批量备份、提取表情图片文件（把 2 万多张表情从 5.6GB 的 DB 中解放出来）。
• 如果你需要精确还原 QQ 原有分组，建议优先使用 QQ 自带导出（导出格式为 EIF）或下方提到的图形化工具。

🧰 其他工具

项目附带了 other_tools/哦哩哩表情管理器.exe：

• 哦哩哩表情管理器（全中文界面）
• 支持导入 / 导出 DB、EIP、EIF 格式的表情包
• QQ 直接导出的格式就是 EIF，可配合本工具实现「QQ 导出 EIF → 管理器整理 → 再导入」的完整流程
• 适合需要精确分组、或把表情重新导回 QQ 的场景

使用方法

# 查看可用分组及每个分组的表情数量
python qq_sticker_export.py --data-dir "D:\QQData\88854321" --list

# 只导出一个分组（如默认收藏 8213）
python qq_sticker_export.py --data-dir "D:\QQData\88854321" --out "D:\stickers" --group 8213

# 导出多个分组
python qq_sticker_export.py --data-dir "D:\QQData\88854321" --out "D:\stickers" --groups 8213,1,4

# 按 QQ 原有分组顺序导出全部分组
python qq_sticker_export.py --data-dir "D:\QQData\88854321" --out "D:\stickers" --all

# 测试：每个分组最多只导 1 张
python qq_sticker_export.py --data-dir "D:\QQData\88854321" --out "D:\stickers" --group 8213 --limit 1

参数说明

参数	说明
--data-dir <目录>	旧版 QQ 用户数据目录（含 CustomFace.db 的文件夹），必填；不填则默认在当前目录找 CustomFace.db
--list	只列出分组和表情数量，不导出
--out <目录>	输出目录（默认当前目录下的 stickers/）
--group <ID>	只导出指定分组 ID
--groups <ID,ID>	导出多个分组，逗号分隔
--all	按 QQ 分组顺序导出所有分组
--limit <N>	每个分组最多导出 N 张（测试用）

项目结构

Export_QQDB_CustomFace/
├── qq_sticker_export.py     # 主导出工具（独立运行，不需要 tools/ 下的脚本）
├── README.md
├── LICENSE
├── other_tools/
│   └── 哦哩哩表情管理器.exe  # 图形化工具：导入/导出 DB、EIP、EIF 表情包
└── tools/
    ├── ole2_lister.py       # OLE2 文件目录结构查看器（查看任意 QQ .db/.dbc 内部结构）
    └── extract_ole2.py      # OLE2 流提取器（把指定 stream 导出为文件）

tools/ 下的脚本是可选的辅助分析工具，用于查看/提取 OLE2 文件内部结构，导出功能本身不依赖它们。它们同样通过命令行参数传入文件路径，不写死任何目录。

环境要求

• Python 3.8+
• 无第三方依赖

许可证

MIT