3步搞定数据格式转换：把散落的抽卡记录统一成UIGF标准JSON
【免费下载链接】HoYo.Gacha✨ 一个非官方的工具，用于管理和分析你的 miHoYo 抽卡记录。（原神 | 崩坏：星穹铁道 | 绝区零）An unofficial tool for managing and analyzing your miHoYo gacha records. (Genshin Impact | Honkai: Star Rail | Zenless Zone Zero)项目地址: https://gitcode.com/gh_mirrors/ho/HoYo.Gacha
当你的抽卡记录散落在游戏截图、第三方工具导出的CSV、以及旧软件的历史备份里时，数据格式转换就不再是"极客专属"的技术活，而是每个老玩家都该掌握的整理术。这篇文章从一个真实换工具场景讲起，带你拆解抽卡记录标准化（UIGF标准）的原理、步骤与常见坑。
一、先看痛点：三份记录，三种语言
小林玩原神三年，抽卡记录分散在三个地方：手机里几百张抽卡截图、某个旧工具导出的CSV表、以及手动整理的"幸运值"Excel笔记。换新分析工具时，对方只认UIGF标准的JSON文件，他瞬间傻眼——这就是典型的数据孤岛问题。
统一格式的价值有三：
- 保底进度、五星出货率等分析才有计算基础；
- 换工具、换设备时记录可无损迁移；
- 本地留档，防账号注销、防记录丢失。
而"UIGF"（统一抽卡记录格式）正是米哈游系游戏（原神、星穹铁道、绝区零）社区共同约定的JSON标准，相当于抽卡数据的"普通话"。
二、逆向拆解：标准JSON到底长什么样
与其空谈标准，不如先看成品。一份UIGF v2.2文件只有两个大块：
| 区块 | 作用 | 关键字段 |
|---|---|---|
info | 文件头信息 | uid、uigf_version、export_time、export_app |
list | 记录数组 | id、gacha_type、item_id、name、rank_type、time、count |
其中time采用 ISO 8601 格式的时间戳，rank_type用数值表示星级（4/5），gacha_type是约定好的卡池编码。这些"翻译规则"就是整个转换链路的灵魂。
从成品反推，每条记录至少要经过"抓取/读取 → 清洗 → 字段映射 → 校验 → 落库"五道工序，下面逐一展开。
三、看懂链路：数据从哪里来，如何变成标准JSON
第一类源头：游戏官方抽卡接口。工具通过你登录后获取的抽卡链接，直接从官方日志接口拉取数据（相关实现见crates/url_scraper/）。这类数据最完整，自带id、gacha_type、item_id、rank_type等原始字段，只需补上uigf_gacha_type等派生字段即可。
第二类源头：其他工具的导出文件。可能是旧版UIGF、星铁SRGF、甚至只有两列的简易CSV。此时最关键的就是"字段映射"——可以把它理解为一位翻译官：
- 卡池编码翻译：原神官方的
302（角色池2）在UIGF里要映射为301（角色池），不同游戏编码体系各不相同； - 名称↔ID互译：工具借助内置元数据（
crates/metadata/），把物品名称翻译成item_id，或反过来把ID翻译成你熟悉的语言； - 时区换算：记录里的时间要按服务器时区统一换算，避免"歪了8小时"的错觉；
- 字段补全：缺失的
count默认补1，缺失的item_type从元数据反查。
转换完的记录会先写入本地数据库（见tauri/src/database/migrations/），形成你自己的"抽卡数据中心"，之后导出成任何格式都只是视图问题。
四、动手实操：导入与导出的完整步骤
在工具的"转换器"入口（前端源码app/pages/Gacha/components/Converters/）里，导入和导出是两条对称流程。
导入一份UIGF/SRGF/CSV文件：
- 选择要导入的文件；
- 选择文件格式（支持UIGF v2.x~v4.x、SRGF v1.0、CSV等）；
- 设定"冲突时怎么处理"——是跳过、保留现有，还是覆盖；
- 确认后观察进度条，完成后会提示本次新增或变更了多少条记录。
导出标准JSON：
- 选择输出文件夹；
- 选择格式与版本（UIGF可选v2.2、v2.3、v4.x等）；
- 按需开关：
pretty美化缩进、minimized精简输出； - 导出完成后可勾选"自动打开文件"快速检查。
结果验证清单：
- ✅ 对比转换前后的记录总数，防止丢数据；
- ✅ 抽查时间戳是否符合 ISO 8601、星级是否为数值；
- ✅ 检查
info.uid与账号是否一致。
💡 小提示：导出文件名会自动带上"应用名_格式_uid_时间戳"的后缀，方便多账号归档。
五、翻车自查：常见问题与备份策略
转换出错不可怕，可怕的是不知道错在哪。按这张表排查：
| 现象 | 可能原因 | 处理方式 |
|---|---|---|
| 提示版本不支持 | 文件是过老的UIGF v1.x | 用支持v2.0+的工具重新导出 |
| 提示uid不一致 | 文件属于另一账号 | 核对info.uid，按账号分别导入 |
| 导入后记录数变少 | 存在隐藏行/列或字段缺失 | 检查原文件完整性，先转CSV再试 |
| 时间对不上 | 时区未统一 | 确认导出的region_time_zone正确 |
⚠️ 任何转换前，建议遵守"原始文件+中间文件+目标文件"三级备份：原件不动，转换产物按日期归档，每周做一次全量备份存到不同位置。遇到个别坏数据时，宁可跳过该条，也不要让整批失败。
六、进阶玩法：从"转一次"到"一直转"
- 跨游戏整合：原神、星穹铁道、绝区零的记录统一转成UIGF，放进一个数据仓库，用同一套逻辑做跨游戏对比分析；
- 批量与自动化：多账号、多文件可批量导入导出；结合定时任务，可实现"新记录自动备份"；
- 深度分析：有了标准化数据，保底概率、角色获取周期、资源投入产出比等分析才真正有据可依。
想亲自体验这套流程，可克隆项目本地运行：
git clone https://gitcode.com/gh_mirrors/ho/HoYo.Gacha
写在最后
从Excel表格、CSV截图到UIGF标准JSON，数据格式转换的本质不是"翻译一次文件"，而是建立起一套可持续的记录管理体系。抓住"标准先行、映射清晰、备份兜底"三个要领，无论是Excel转UIGF还是多游戏数据整合，你的抽卡历史就不再是孤岛，而是一座随时可挖掘的数据金矿。🚀
下一步建议：挑一份现有的抽卡记录备份出来做首次转换实验，用今天的验证清单核对一遍，你的标准化之旅就正式开始了。
【免费下载链接】HoYo.Gacha✨ 一个非官方的工具，用于管理和分析你的 miHoYo 抽卡记录。（原神 | 崩坏：星穹铁道 | 绝区零）An unofficial tool for managing and analyzing your miHoYo gacha records. (Genshin Impact | Honkai: Star Rail | Zenless Zone Zero)项目地址: https://gitcode.com/gh_mirrors/ho/HoYo.Gacha
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
