企业官网建设流程全解析

HoYo.Gacha 抽卡记录转换终极指南：从 Excel 手账到 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

如果你是原神、星穹铁道或绝区零的玩家，大概都经历过同一件事：抽卡记录记在 Excel 里、截图里、备忘录里，换一台电脑就全部断档。抽卡记录转换的核心，就是把散落的数据收拢成一套通用格式。本文以开源工具 HoYo.Gacha 为例，用一条完整流程，带你完成从 Excel 手账到UIGF 标准JSON 文件的转换，一次标准化，终身可复用。

第一幕｜从一次换电脑说起：为什么你的抽卡数据会乱

还原现场：Excel 手账的三大软肋

很多玩家习惯用 Excel 记账：日期一列、物品一列、星级一列。看起来井井有条，但真到用的时候处处碰壁：

1. 格式不统一——有人记"2025/1/1"，有人记"2025年1月1日"，还有人只写"元旦"。
2. 字段不全——缺卡池类型、缺保底计数，事后无法回溯。
3. 无法互通——想换个抽卡分析工具，对方要的是 JSON，你的数据却困在.xlsx里。

数据一旦"困住"，价值就打折了：概率算不准、保底说不清、换工具就要重记一遍。

三种"方言"：认识 UIGF 标准与它的兄弟格式

要打破孤岛，先要认识市面上常见的三种"语言"：

HoYo.Gacha 同时支持 UIGF v2.0~v3.0（经典版）与 v4.0~v4.2（新版）、SRGF v1.0，以及 CSV 导出。这意味着无论你的记录来自哪种工具，都有通道可以汇入同一个仓库。

第二幕｜认识引擎：HoYo.Gacha 的导入导出转换器

一张表看懂支持的格式

打开 HoYo.Gacha，进入账号的"转换器"入口，你会看到导入（Importer）和导出（Exporter）两个对话框。它们的格式支持范围各不相同：

💡技巧提示：跨游戏合并记录时，优先选新版 UIGF。它用一个 JSON 文件就能装下多个游戏、多个账号的数据，是真正的"全家桶"格式。

导出与导入的分工

• 导出（Exporter）：把本地数据库里的记录，翻译成指定格式的文件，输出到你自己选的文件夹。
• 导入（Importer）：把别人或旧工具导出的标准文件，读回本地数据库，自动去重、补全。

两者共同构成了"进得来、出得去"的闭环，这正是数据流通的关键。

转换选项：pretty、minimized 是什么意思

导出时你会看到几个开关，别被英文吓到：

⚠️注意警告：Minimized 会省略物品名、类型等"冗余"字段，如果接收方工具依赖这些字段，请保持关闭。

第三幕｜备料：把 Excel 整理成可转换的规范数据

对照这份字段清单检查你的表格

转换前，先确认你的 Excel 里有没有这些关键列。缺了它们，转换后必然出问题：

1. 抽卡时间——建议统一为YYYY-MM-DD HH:mm:ss格式
2. 物品名称——如"神里绫华""夜兰"
3. 星级——纯数字（3 / 4 / 5），不要写"五星"
4. 卡池类型——角色、武器、常驻、新手等
5. UID——账号归属标识，一个文件只属于一个账号

💡技巧提示：在 Excel 中预先设置"数据验证"，限定时间和星级列的输入格式，能大幅降低后续转换的错误率。

三步体检：透视表、去重、时间格式化

建议在转换前花三分钟做一次体检：

1. 用数据透视表统计各星级数量，和游戏内记录比对，确认没有整行遗漏。
2. 用"删除重复项"清理明显的重复行。
3. 全选时间列，统一单元格格式为yyyy-mm-dd hh:mm:ss。

从 Excel 出发的三条路径怎么选

🚀进阶玩法：路径 A 是效率最高的——HoYo.Gacha 能直接读取浏览器缓存生成抽卡链接并拉取全量记录，相当于把"官方账本"直接搬回家，比任何手工表格都可靠。

第四幕｜实战：从手账到 UIGF 标准 JSON 的完整流程

第一步：确认账号与记录归属

在工具中先确保账号存在且 UID 正确。UID 是整条流程的锚点——导出文件会写入 UID，导入时也会校验 UID 一致性，任何错位都会导致失败。

第二步：选择导出格式与版本

按你的目标选择导出格式：

• 只玩原神、要兼容老工具 →Classic UIGF v2.2 或 v2.3
• 多游戏合并、面向新生态 →新版 UIGF v4.2
• 需要二次加工数据 →CSV

选定格式后，选择目标文件夹，工具会自动生成类似HoYo.Gacha_Uigf_100000000_20260814_132800.json的规范命名文件。

第三步：导出并验证 JSON 质量

导出完成后，建议做三件事验证质量：

1. 打开 JSON，检查info区的时间戳、version是否正确。
2. 抽查几条记录的time、rank_type、gacha_type。
3. 对比导出前后的记录总数，确认零丢失。

⚠️注意警告：转换前务必备份原始 Excel，建议用"另存为"创建副本再操作，给回滚留一条后路。

第五幕｜反向操作：把标准文件导入你的数据仓库

导入前的版本兼容检查

导入时，工具会先解析文件头部声明的版本号，再与自身支持范围比对。超出范围的版本会直接拒绝并给出明确提示。因此收到别人的文件时，先确认：

• 文件是 UIGF 还是 SRGF？
• 版本号是否在支持列表内？
• UID 是否与你的目标账号一致？

冲突处理：遇到重复记录怎么办

导入对话框里有个SaveOnConflict（冲突保存策略）选项，这是防重复的关键：

💡技巧提示：第一次迁移建议选 Nothing，跑完看统计数字，再决定是否需要更新。

导入后的完整性验证

导入完成会弹出成功提示与变更条数。随后刷新记录列表，核对：

1. 总数是否与源文件条数吻合；
2. 各卡池分类数量是否正常；
3. 最新一条记录时间是否合理。

确认无误后，你的数据仓库就完成了"吞并"，后续所有分析都会自动基于合并后的全集进行。

第六幕｜原理拆解：转换引擎内部的三层"翻译官"

不懂原理也能用工具，但懂了原理，出问题时你能自己判断根源。HoYo.Gacha 的转换引擎（位于tauri/src/business/converters.rs）本质上是三个"翻译官"接力工作：

解析层：听懂每一种"方言"

这一层负责读取文件，识别它是 UIGF、SRGF 还是 CSV，并理解各自的字段结构。不同版本的 UIGF 字段要求不同——例如 v2.2 要求必须提供name和item_type，而 v2.3 起改为必须提供item_id。解析层就像翻译官先"听"出对方说的是哪种话。

映射层：字段对齐与类型转换

解析之后进入映射：把源格式的字段逐一对应到内部统一的GachaRecord结构。这里有个典型的智能行为——卡池类型映射：原神的"角色活动2"会被映射为标准的"角色活动"类型，避免同一卡池在不同工具里被算成两种东西。

校验层：UID、时区与必填字段的层层把关

最后是质量关卡，转换引擎会逐条检查：

• UID 校验：格式合法且与账号一致；
• 时区换算：按记录所在服务器的时区统一换算，避免"跨服时间差"；
• 必填字段：缺失关键字段的记录会报错并给出游标位置，方便你定位问题行。

🚀进阶玩法：导出时工具还会借助内置元数据，把物品名翻译成你偏好的语言（如英文界面导出英文名），这一步在映射层自动完成，无需手工替换。

第七幕｜避坑手册：三大高频问题的排查决策树

问题一：格式报错，文件打不开或解析失败

1. 文件本身是否损坏？
   • 用 Excel/WPS 尝试打开原文件，能正常打开则排除损坏。
2. 表格结构是否规范？
   • 确认第一行是表头，且表头与标准字段对应。
   • 存在合并单元格或空行？取消合并、删除空行后重试。
3. 仍失败？
   • 用"另存为 CSV"中转一次，再尝试导入。

问题二：转换后数据丢失或数量不符

1. 字段是否全部映射？
   • 对照第三幕的字段清单，检查 Excel 是否有未对齐的列。
2. 是否存在隐藏行/列？
   • 取消隐藏后重新转换，隐藏内容不会被读取。
3. 文件是否过大？
   • 将 Excel 拆分为多个小文件分批转换，逐批核对计数。

问题三：导入失败或记录错乱

1. JSON 格式是否合法？
   • 用任意 JSON 校验工具检查括号、引号与编码（必须为 UTF-8）。
2. UIGF 版本是否匹配？
   • 确认文件的version字段在工具支持范围内。
3. UID 是否一致？
   • 文件内 UID 与目标账号 UID 不同会直接拒绝导入。

第八幕｜最佳实践：可以直接照抄的行动清单

数据管理黄金清单

每次转换前

1. 备份原始 Excel（另存为副本，勿在原文件上操作）。
2. 用数据透视表核对各星级总条数。
3. 统一时间格式，删除重复项。

每次转换后4. 对比转换前后记录总数。 5. 抽查时间戳、星级、卡池类型三个关键字段。 6. 将 UIGF 目标文件按日期归档保存。

版本选择与长期维护

版本选择

1. 面向新工具生态 → 新版 UIGF v4.2。
2. 需要兼容老工具 → Classic UIGF v2.2/v2.3。
3. 星铁老数据 → SRGF v1.0。

长期维护4. 定期（建议每版本更新后）从官方接口刷新记录。 5. 每年导出一次 UIGF 全量备份，存到不同介质。 6. 迁移电脑时，同步带走本地数据库文件与最新导出文件。

到这里，你已经拥有了一条完整的数据流水线：Excel 手账或官方数据 → HoYo.Gacha 本地仓库 → UIGF 标准 JSON。跨工具共享、跨游戏合并、概率分析、历史追溯，全都建立在"标准格式"这一块地基上。记住，数据标准化是第一步，也是回报率最高的一步——现在就打开 HoYo.Gacha，导出你的第一份 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