配置表工具链:从 Excel 到运行时数据,导出、代码生成、校验与加载

1770 字
9 分钟
配置表工具链:从 Excel 到运行时数据,导出、代码生成、校验与加载

一、为什么需要工具链#

游戏中的大量数据由策划配置:物品、技能、怪物、关卡、任务、商店、掉落、文本。策划最熟悉的工具是 Excel,而程序需要的是类型明确、加载快、不出错的数据。

配置表工具链连接两者:

策划编辑 Excel
│ 导表工具
├─▶ 数据文件(二进制 / JSON) → 客户端、服务器加载
├─▶ C# 数据类与加载代码(自动生成) → 程序直接使用,强类型
└─▶ 校验报告 → 配置错误在导表时就被发现

目标是:策划改完表、导出,程序不需要改任何代码就能拿到新数据;错误在导表时被拦截,而不是上线后才发现。

二、表头约定#

每张表的前几行用来描述字段:

行内容例子
字段名程序中使用的名字id name quality price skills
类型字段的数据类型int string int int int[]
导出目标这个字段给谁用cs(双端)c(仅客户端)s(仅服务器)
说明给策划看的中文注释编号、名称、品质、售价、技能列表
数据行1001 生命药水 2 50 3001,3002

复杂类型的表达:

类型写法举例
数组3001,3002,3003
结构(x=1,y=2) 或者拆成多列
结构数组物品奖励 1001:5;1002:10(ID:数量;ID:数量)
枚举写枚举名而不是数字:Physical、Magic
引用其他表写另一张表的 ID,并在校验中检查存在性

约定好统一的语法,并由工具解析和校验,而不是每张表各自约定、程序各自解析。

三、导出格式#

格式优点缺点
JSON可读,方便排查体积大、解析慢、解析时产生大量 GC
二进制(自定义或 Protobuf)体积小、加载快不可读
FlatBuffers不需要反序列化,读取时直接访问字段,可以按需读取构建复杂,体积比 Protobuf 大

配置表通常数据量大、只读,加载速度和内存是主要关注点,所以正式包一般使用二进制格式,开发时可以同时导出 JSON 方便查看。格式的对比见 序列化与网络协议。

四、代码生成#

根据表头自动生成数据类和加载代码:

// 自动生成,不要手动修改
public sealed partial class ItemConfig
{
public int Id { get; private set; }
public string Name { get; private set; }
public int Quality { get; private set; }
public int[] Skills { get; private set; }
internal static ItemConfig Read(ByteReader r) =>
new ItemConfig { Id = r.ReadInt(), Name = r.ReadString(), Quality = r.ReadInt(), Skills = r.ReadIntArray() };
}
public sealed class ItemTable
{
readonly Dictionary<int, ItemConfig> _map = new();
public IReadOnlyCollection<ItemConfig> All => _map.Values;
public ItemConfig Get(int id) => _map.TryGetValue(id, out var v) ? v : null;
// 加载代码……
}
  • 程序使用强类型的字段:Tables.Item.Get(1001).Name,字段改名或删除时编译就会报错,而不是运行时出问题;
  • 生成的类用 partial,需要附加的计算属性或方法写在另一个文件中,重新生成时不会被覆盖(见 partial);
  • 配置数据在运行时应该是只读的:属性的 setter 设为私有,集合对外暴露只读接口,防止某处代码修改了配置,影响到所有使用它的地方。

五、校验#

导表时的校验是工具链最有价值的部分之一,它把错误挡在打包之前:

校验例子
类型int 列中填了文字
必填物品名称为空
唯一性两行的 ID 重复
范围概率不在 0 到 1 之间,品质超出定义的范围
引用技能表中引用的特效 ID 在特效表中不存在;奖励中的物品 ID 不存在
资源填写的图标路径、Prefab 路径对应的资源不存在
业务规则一组掉落的权重之和为 0;关卡的解锁条件引用了还没开放的关卡

校验失败时给出明确的位置(哪张表、哪一行、哪一列、什么问题),让策划自己就能修正。

六、运行时的加载与索引#

  • 按需加载:配置表很多时,不要在启动时把所有表都加载进内存。第一次访问某张表时再加载(懒加载),或者按功能模块分组加载。
  • 建立索引:最常用的是按 ID 查找,用字典建立索引;其他常用的查询(按类型、按关卡)也可以预先建立分组。
  • 内存:大量重复的字符串(比如很多物品的类型名称)可以在加载时去重;或者使用 FlatBuffers 这类不需要完全反序列化的格式。
  • 热更新:配置表的数据文件作为资源一起热更新(见 热更新)。如果生成的代码也有变化(新增了字段),代码也需要热更新。

七、前后端共用#

服务器同样需要配置(掉落、商店价格、技能伤害)。同一份 Excel 同时为客户端和服务器导出,保证双方使用的数据一致:

  • 通过字段的导出目标,只给客户端导出界面相关的字段(图标、描述),只给服务器导出敏感的字段(掉落概率、怪物刷新规则);
  • 敏感数据不应该出现在客户端的包中,否则玩家解包就能看到。

八、多人协作#

  • Excel 是二进制文件,版本控制中无法合并。两个人同时修改同一张表就会冲突。常见的应对:表按功能拆分得更细;修改前先锁定文件;或者改用基于文本的格式保存源数据。
  • 导表纳入 CI 流程:提交后自动导出和校验,失败时通知修改者(见 自动化打包)。
  • 国内项目常用的开源导表工具(比如 Luban)已经实现了上面的大部分功能:多种数据格式、代码生成、校验、前后端分离导出,可以直接采用,而不必从零开发。

常见追问#

配置表工具链做了什么? 把策划编辑的 Excel 导出成程序使用的数据文件,自动生成强类型的数据类和加载代码,并在导出时做数据校验。

配置表用什么格式导出? 开发时可以用 JSON 方便查看,正式包一般用二进制(自定义、Protobuf)或 FlatBuffers,体积小、加载快、GC 少。

为什么要生成代码,而不是手写读取? 强类型,字段变化时编译期就能发现;减少重复劳动和手写错误;加载代码统一、高效。

导表时应该做哪些校验? 类型、必填、唯一性、数值范围、表之间的引用、资源是否存在、业务规则。

配置表在运行时怎么管理? 按需加载,按 ID 建立字典索引,数据只读,常用的查询预先分组。

服务器的敏感配置怎么处理? 按字段的导出目标分别导出,敏感字段只导给服务器,不打进客户端的包中。

文章分享

如果这篇文章对你有帮助,欢迎分享给更多人!

配置表工具链:从 Excel 到运行时数据,导出、代码生成、校验与加载
https://xslab.cloud/posts/design/config-pipeline/
作者
LuxFire
发布于
2026-10-14
许可协议
CC BY-NC-SA 4.0
相关文章 智能推荐
1
背包与物品系统设计:配置与实例、数据结构、堆叠、整理与同步
项目设计/业务系统 物品的配置与实例如何分离;可堆叠物品与带属性的独立物品;背包的数据结构选择;添加、移除、移动、拆分、整理等操作的规则与边界情况;变化通知与界面刷新;与服务器的同步;以及背包界面的实现要点。
2
多语言本地化:文本、字体、图片、排版与流程
项目设计/架构 本地化需要处理哪些内容;文本的 Key 设计、参数与复数;运行时切换语言;不同语言的字体与字符集;文字长度变化带来的排版问题;从右到左的语言;图片与音频资源的本地化;日期、数字、货币的格式;以及翻译的流程与常见坑。
3
技能与 Buff 系统设计:属性、技能、效果、Buff 的拆分与数据驱动
项目设计/业务系统 技能系统的整体结构;属性系统与修改器的计算顺序;技能的释放流程、时间轴与目标选择;把技能拆成可复用的原子效果;Buff 的生命周期、叠加规则与事件触发;伤害计算的流程;数据驱动与技能编辑器;以及联网游戏中的权威与表现。
4
存档系统设计:数据模型、序列化、版本迁移、安全写入、加密与云存档
项目设计/业务系统 存档要保存什么、存档数据与运行时对象如何分离;序列化格式的选择;存档的版本号与迁移;防止写入时崩溃导致存档损坏;保存的时机与异步保存;PlayerPrefs 的适用范围;加密与防篡改的作用和局限;云存档的冲突处理。
5
任务与成就系统设计:条件配置、事件驱动的进度统计、状态流转与重置
项目设计/业务系统 任务的类型与配置结构;把完成条件抽象成可配置的条件类型;用事件驱动进度更新以及按事件类型建立索引;任务的状态流转;每日、每周任务的重置;成就的累计统计、分级与补发;以及与服务器、红点的配合。
随机文章 随机推荐
Profile Image of the Author
LuxFire
Hello, I'm LuxFire.
公告
欢迎来到我的博客!这是一则示例公告。
音乐
封面

音乐

暂未播放

0:00 0:00
暂无歌词
分类
标签
站点统计
文章
60
分类
6
标签
164
总字数
171,869
运行时长
0 天
最后活动
0 天前

文章目录