Unity 商业项目中，我为什么要做配置表工具链

Unity 商业项目中，我为什么要做配置表工具链

在游戏项目中，配置表是一个非常基础、但又非常容易被低估的系统。

很多项目刚开始的时候，配置表可能只是几个简单的 CSV、Excel 或 Json 文件。

比如：

• 角色配置
• 道具配置
• 技能配置
• 关卡配置
• 多语言配置
• 新手引导配置
• 商城配置

项目小的时候，直接读取这些文件并不难。

真正困难的地方不在于“怎么读取配置表”，而在于：

配置表多了以后，如何保证数据是正确的。

这也是我在 MyFramework 中做配置表工具链的主要原因。

项目地址：

https://github.com/ZHOURUIH/MyFramework

配套服务器框架：

https://github.com/ZHOURUIH/MyServerFramework

这篇文章主要聊一下：

• 为什么游戏项目需要配置表工具链
• 配置表系统真正难的地方是什么
• 为什么我选择 CSV 作为配置表格式
• 配置表编辑器需要解决哪些问题
• 为什么要生成客户端和服务器代码
• 配置表检查对商业项目有什么价值

一、配置表的问题不在于读取，而在于检查

很多人刚开始做配置表时，关注点通常是：

• 怎么读取 Excel
• 怎么读取 CSV
• 怎么读取 Json
• 怎么转成二进制
• 怎么在 Unity 里加载

这些当然都需要做。

但在真实商业项目里，配置表最麻烦的问题通常不是读取，而是数据错误。

比如：

• ID 填错
• ID 重复
• 引用了不存在的 ID
• 枚举值写错
• 资源路径不存在
• 字段类型不对
• 客户端和服务器字段不一致
• 某个字段为空，但运行时又必须使用
• 某个配置引用了一张已经删除的表
• 某个道具配置了一个不存在的图标

这些问题如果只能等运行时才发现，排查成本会非常高。

尤其是当配置表数量很多、数据量很大、多人协作维护时，人工检查几乎不可能保证稳定。

所以我认为配置表系统真正需要解决的问题是：

尽可能在编辑阶段发现错误，而不是等到运行时才报错。

这也是配置表工具链最重要的价值。

二、为什么我选择 CSV

MyFramework 使用 CSV 作为配置表格式。

原因很简单：

CSV 足够简单，足够稳定，也足够容易处理。

相比一些更复杂的格式，CSV 有几个优点。

1. 格式简单

CSV 本质上就是文本表格。

它没有复杂的文档结构，也没有太多额外信息。

这意味着解析、对比、版本管理都比较直接。

对于程序来说，CSV 很容易被读取、检查和转换。

2. 方便版本管理

配置表在项目中通常会频繁修改。

如果使用二进制格式，Git 很难看出具体改了什么。

而 CSV 是文本格式，修改内容可以直接在版本管理工具中看到。

这对排查问题非常有帮助。

比如某个版本上线后发现技能伤害异常，就可以直接查看对应配置表字段在哪次提交中被改过。

3. 容易和代码生成工具配合

CSV 的表头、字段类型、数据行都比较清晰。

只要约定好表头规则，就可以很方便地生成：

• 客户端读取代码
• 服务器读取代码
• 字段检查代码
• 引用检查代码
• 枚举检查代码
• 资源路径检查代码

这也是我选择 CSV 的原因之一。

4. 不依赖复杂外部环境

有些项目直接依赖 Excel 文件。

Excel 功能很强，但也会带来一些问题。

例如版本差异、格式隐藏信息、合并冲突、平台依赖、解析库依赖等。

CSV 虽然简单，但对于游戏配置来说已经足够。

我更希望配置表工具链本身是清晰、可控、可维护的。

三、配置表编辑器要解决什么问题

很多人理解的配置表编辑器，只是一个“能编辑表格的工具”。

但我认为真正有价值的配置表编辑器，重点不是编辑，而是检查。

因为表格本身可以用很多工具编辑。

真正重要的是：

编辑时就能发现错误。

在 MyFramework 的配置表工具链中，我希望表格编辑器至少解决以下问题。

1. 字段类型检查

每一列字段都应该有明确类型。

比如：

• int
• float
• string
• bool
• enum
• list
• vector
• resource path

如果字段声明是 int，就不应该填字符串。

如果字段声明是 enum，就不应该填一个不存在的枚举值。

如果字段声明是 list，就应该检查列表格式是否正确。

这类问题越早发现越好。

否则等到运行时解析失败，或者解析成功但数据不符合预期，排查会很麻烦。

2. ID 唯一性检查

游戏配置中最常见的主键就是 ID。

例如：

• 道具 ID
• 技能 ID
• 怪物 ID
• 任务 ID
• 剧情 ID
• 商城商品 ID

这些 ID 一旦重复，就可能导致读取结果覆盖、查找错误、逻辑异常。

所以配置表工具链必须检查 ID 唯一性。

这类错误不应该等到运行时才发现。

3. 表格引用检查

很多配置表之间会互相引用。

例如：

• 技能表引用特效表
• 怪物表引用掉落表
• 任务表引用道具表
• 商城表引用商品表
• 新手引导表引用 UI 表
• 多语言表引用文本 ID

如果引用的 ID 不存在，就应该在编辑阶段报错。

否则运行时可能会出现空引用、资源加载失败、界面显示异常等问题。

在大型项目中，表格引用关系非常复杂。

如果没有工具检查，人工基本无法保证完全正确。

4. 资源路径检查

配置表中经常会填写资源路径。

比如：

• 图标路径
• Prefab 路径
• 音效路径
• 特效路径
• 图集路径
• UI 路径

如果路径写错，运行时加载资源就会失败。

这类错误也应该在编辑阶段检查出来。

尤其是项目资源经常移动、重命名、删除时，路径检查非常重要。

5. 枚举合法性检查

很多配置字段本质上是枚举。

比如：

• 职业类型
• 道具类型
• 技能类型
• 品质类型
• 任务类型
• 奖励类型
• 触发条件类型

如果配置表里填了一个代码中不存在的枚举值，就会导致运行时逻辑异常。

所以配置表工具链需要知道枚举定义，并检查表格中的枚举值是否合法。

6. 空值检查

有些字段允许为空，有些字段不允许为空。

例如道具名称通常不应该为空。

资源路径有时可以为空，有时必须存在。

如果字段是否允许为空没有规则，那么很多错误就只能运行时才暴露。

所以表格工具链需要支持字段级别的规则检查。

四、为什么要做代码生成

配置表工具链中，代码生成是非常重要的一部分。

如果没有代码生成，读取配置表时通常会出现大量手写解析逻辑。

比如：

• 手动读取字段
• 手动转换类型
• 手动处理默认值
• 手动写查询函数
• 手动维护字段名
• 手动同步客户端和服务器结构

这些代码本身重复度很高，而且很容易出错。

所以 MyFramework 的配置表工具链会根据配置表结构自动生成代码。

1. 生成客户端代码

客户端需要读取配置表，并在游戏逻辑中使用。

例如：

• 根据道具 ID 查询道具配置
• 根据技能 ID 查询技能配置
• 根据任务 ID 查询任务配置
• 根据多语言 ID 查询文本
• 根据资源 ID 查询资源路径

如果这些代码都手写，维护成本会很高。

通过代码生成，可以让表结构和读取代码保持一致。

当表格字段变化时，重新生成代码即可。

这样可以减少很多手写错误。

2. 生成服务器代码

很多游戏配置不只客户端需要使用，服务器也需要使用。

例如：

• 技能数值
• 掉落配置
• 商城配置
• 任务配置
• 战斗相关配置
• 角色成长配置

如果客户端和服务器各自维护一套结构，就很容易不一致。

所以我更倾向于让客户端和服务器都从同一份配置表结构生成代码。

这样至少可以保证：

客户端和服务器理解的是同一份配置结构。

这对于有服务器的游戏项目非常重要。

3. 生成检查代码

配置表工具链不只是生成读取代码，还可以生成检查逻辑。

例如：

• 某个字段引用哪张表
• 某个字段应该是哪个枚举
• 某个字段是否必须存在资源路径
• 某个字段是否允许为空
• 某个字段是否需要唯一

这些规则如果写在工具里，就可以在编辑阶段自动检查。

这比运行时再写各种判断更加可靠。

4. 减少字符串字段名

手写配置读取代码时，经常会出现大量字符串字段名。

例如：

• "id"
• "name"
• "icon"
• "skillID"
• "rewardList"

字符串字段名的问题是，写错了编译器也不会报错。

通过代码生成，可以把字段变成明确的成员变量。

这样使用配置时更加安全，也更加直观。

五、配置表错误为什么要尽早暴露

在商业项目中，很多 Bug 并不是代码逻辑错误，而是数据错误。

尤其是配置表相关 Bug，常常会表现得很隐蔽。

比如：

• 某个技能释放失败
• 某个道具图标不显示
• 某个任务无法完成
• 某个怪物不掉落物品
• 某个商店商品价格异常
• 某个新手引导卡住
• 某个 UI 文本显示为空

这些问题表面看起来像代码 Bug，但实际原因可能只是配置表中某个字段写错了。

如果没有工具链支持，程序可能要花很多时间去调试逻辑，最后才发现是数据问题。

所以配置表工具链的目标不是“让读取更快”这么简单。

更重要的是：

让错误尽早暴露。

最好是在编辑配置表时就能发现。

其次是在生成代码时发现。

再次是在打包前检查时发现。

最差才是在运行时发现。

越晚发现，成本越高。

六、为什么配置表工具链对长期项目很重要

小项目中，配置表工具链的价值可能不明显。

因为表少，人少，数据少。

很多问题靠人工就能处理。

但长期项目完全不同。

长期项目会遇到几个必然问题。

1. 表会越来越多

项目越做越久，配置表数量一定会增加。

最开始可能只有角色、道具、技能几张表。

后来会出现：

• 活动表
• 任务表
• 引导表
• 商城表
• 成就表
• 掉落表
• 多语言表
• 剧情表
• 音效表
• 特效表
• UI 表

表越多，表之间的引用关系越复杂。

没有工具检查，后期维护成本会越来越高。

2. 字段会不断变化

项目开发过程中，策划和程序会不断调整配置结构。

例如：

• 某个字段改名
• 某个字段类型改变
• 某个字段拆成多个字段
• 某个字段废弃
• 某个字段变成列表
• 某个字段从客户端字段变成服务器字段

如果没有代码生成，每次字段变化都要手动改很多地方。

这很容易漏改。

3. 参与的人会越来越多

配置表不是只有程序会改。

策划、运营、测试都有可能参与配置。

这意味着不能假设所有人都理解代码逻辑。

工具链必须帮助他们发现错误，而不是把所有检查压力都交给程序。

4. 数据错误会越来越难排查

项目越大，数据错误越难定位。

一个运行时表现异常，背后可能涉及多张表、多条数据、多种引用关系。

如果没有工具链提前检查，排查问题会非常浪费时间。

所以长期项目必须依赖工具，而不是只依赖经验。

七、配置表工具链和服务器框架的关系

MyFramework 不只是一个 Unity 客户端框架。

它还有配套的服务器框架 MyServerFramework。

这也是配置表工具链设计时需要考虑的重要点。

因为很多配置并不是只给客户端用。

服务器同样需要配置。

例如：

• 角色成长
• 战斗数值
• 技能参数
• 掉落规则
• 商城价格
• 任务条件
• 奖励内容

如果客户端和服务器读取的是不同结构，或者生成逻辑不一致，就容易出现问题。

所以配置表工具链应该尽量保证：

• 同一份配置结构
• 同一套字段定义
• 客户端和服务器分别生成代码
• 客户端和服务器都能使用相同的数据规则
• 检查逻辑尽量在生成阶段完成

这样可以减少客户端和服务器之间因为配置理解不一致导致的问题。

对于有服务器的游戏项目，这一点非常重要。

八、为什么配置表工具链不是简单的“表格转代码”

很多人听到配置表代码生成，可能会理解成：

把表格字段生成成一个类。

但这只是最基础的部分。

真正有价值的配置表工具链，应该至少包含几个层面。

1. 表结构描述

工具需要知道每一列代表什么。

比如：

• 字段名
• 字段类型
• 默认值
• 是否允许为空
• 是否客户端使用
• 是否服务器使用
• 是否参与检查
• 是否引用其他表
• 是否对应资源路径

如果没有表结构描述，就很难做完整检查。

2. 数据合法性检查

工具需要检查数据本身是否符合规则。

比如：

• 类型是否正确
• 枚举是否合法
• ID 是否重复
• 引用是否存在
• 路径是否存在
• 列表格式是否正确

这是配置表工具链的核心价值。

3. 代码生成

工具需要根据表结构生成客户端和服务器代码。

这样可以减少手写解析逻辑，并保持结构一致。

4. 运行时读取

生成后的代码还需要配合运行时读取系统使用。

配置表最终还是要被游戏逻辑查询。

所以运行时查询接口也需要稳定、清晰、易用。

5. 工程检查集成

配置表检查最好不要只在编辑表格时运行。

它也应该能集成到工程检查流程中。

比如打包前统一检查配置表和资源引用，避免错误进入发布包。

所以配置表工具链应该是完整流程，而不是一个孤立的小工具。

九、MyFramework 中配置表工具链的目标

在 MyFramework 中，我希望配置表工具链解决的不是“能不能读取配置”这种基础问题，而是更偏工程化的问题。

核心目标有几个。

1. 让配置表错误尽早发现

越早发现错误，成本越低。

最好在编辑表格时就发现。

其次在生成代码时发现。

再次在工程检查时发现。

尽量不要等到运行时才发现。

2. 让客户端和服务器结构一致

同一份配置表结构，生成客户端和服务器代码。

减少两端理解不一致的问题。

3. 减少重复手写代码

解析代码、字段访问代码、注册代码、检查代码，都尽量由工具生成。

程序只关注真正的业务逻辑。

4. 降低长期维护成本

项目越做越久，配置表越多，字段越多，引用越复杂。

工具链的作用就是降低这些长期维护成本。

5. 支持商业项目持续迭代

配置表工具链不是为了 Demo 好看，而是为了长期项目能稳定迭代。

尤其是 RPG、MMO、SLG、模拟经营这类数据量比较大的项目，配置表工具链非常重要。

十、这个工具链适合什么项目

配置表工具链并不是所有项目都必须做得很复杂。

如果只是一个很小的 Demo，直接 Json 或 ScriptableObject 也可以。

但如果你的项目符合下面这些情况，就很适合引入类似工具链：

• 配置表数量比较多
• 配置之间存在大量引用关系
• 客户端和服务器都需要读取配置
• 策划需要频繁修改数据
• 项目需要长期维护
• 数据错误排查成本较高
• 项目需要稳定打包和发布
• 希望尽量在编辑阶段发现错误

对于这类项目来说，配置表工具链不是锦上添花，而是非常实用的基础设施。

结语

配置表系统看起来很普通。

但在长期 Unity 商业项目中，它非常重要。

我做 MyFramework 的配置表工具链，并不是为了简单读取 CSV，而是为了让配置表从“数据文件”变成一套可检查、可生成、可维护的工程流程。

它的核心价值不是读取，而是：

提前发现错误。

统一客户端和服务器结构。

减少重复手写代码。

降低长期维护成本。

如果你正在做 Unity 商业项目，尤其是 RPG、MMO、SLG、模拟经营这类数据量较大的项目，那么配置表工具链一定值得认真设计。

项目地址：

https://github.com/ZHOURUIH/MyFramework

配套服务器框架：

https://github.com/ZHOURUIH/MyServerFramework