导表这件事，麻烦的往往不是把 Excel 读进来，而是项目跑一段时间之后冒出来的这些情况。
同一张表，客户端要 JSON、服务端要另一种格式，一次导出跑两遍，两边的目录和字段名还容易互相覆盖。表头改了几个字段，线上包更新完才发现服务端少了一列。最难受的是报错只给一句「导表失败」，文件、Sheet、行列全都要自己翻。
coo-xl-maker 是我写的 Cocos Creator 3.x 导表插件。这里把表头设计、分流逻辑和命令行部分写清楚，顺便收集一下大家对填表规范的想法。
表头怎么设计
表头分四层，DESC、TYPE、CLIENT、SERVER。
- DESC 是字段备注。
- TYPE 声明字段数据类型。
- CLIENT 和 SERVER 分别声明客户端和服务端要导出的字段名和范围。
这样设计的出发点很简单，客户端和服务端对同一张表的需求本来就不一样。两边字段名也可以不同，服务端重命名字段不会波及客户端。同一列数据可以只导出到服务端或客户端，不需要导出的一端字段留空就行。
导出分流
批量勾选工作簿之后，客户端和服务端各配一套输出目录、格式和扩展名，互不干扰。支持 JSON、CSV、BIN 三种格式，另外有增量导出（按文件修改时间跳过未变化的表）、强制导出和并发数设置。
增量判断的口径和命令行一致，面板上看到的跳过结果就是命令行的结果，不存在两套逻辑。
BIN 格式是什么
BIN 是插件自带的一种二进制封装，运行时数据以二进制形式存储。相比 JSON / CSV 明文，字段名和值不会直接摊在文件里，客户端配置的直接可读性会低一些。可以在一定程度上加强数据安全。
三种格式的体积和读取速度
拿 10000 行、16 字段的同一份配置表（含 float、list、dict）做了实测，三种格式导出后数据完全一致，checksum 相同。读取耗时包含读文件和完整解码，每个样本新起一个 Node.js 进程、无预热、31 次取中位数，未清操作系统磁盘缓存。JSON 走原生 JSON.parse，CSV 和 BIN 走随插件的运行时读取实现。
| 格式 | 文件大小 | 读取+解码耗时 |
|---|---|---|
| JSON | 3,293,299 字节 | 8.57 ms |
| CSV | 1,633,442 字节 | 25.71 ms |
| BIN | 1,111,831 字节 | 19.03 ms |
换算一下，BIN 体积约为 JSON 的三分之一，CSV 约为 JSON 的一半；读取耗时 BIN 比 CSV 快 26% 左右。JSON.parse 本身最快（v8还是太权威了），但这是用三倍体积换的，包体大小和热更下载流量上 BIN 最省。CSV 的优势是肉眼可读，适合调试阶段对数据。
BIN 是小端序的二进制布局，表头存字段名和类型 id，数据区逐行按类型编码，dict 和 list 自带元素类型 id，客户端不用额外带一份 schema 就能解码。
报错长什么样
导表失败的时候，错误信息带文件、Sheet、目标（客户端或服务端）、行列、字段、类型和值。类型转换失败会指出具体是哪个字段的哪个值，重复字段名、无有效业务列也有对应提示。
目标是让报错能直接定位到单元格，不用凭感觉猜。
导入回写
JSON 可以按主键匹配回写 Excel，主键相同的行更新，字段缺失或类型不匹配时保留上下文。适合运营改完数据之后回填表格，或者热更数据调整后做二次加工。
命令行和 CI
面板之外还有两个入口，随插件提供的 Node.js 封装和四平台编译版 Go CLI。校验、增量判断、错误上下文和面板完全一致，不打开 Creator 也能接 Shell、构建脚本和 CI。
node extensions/coo-xl-maker/static/export.mjs \
--src config \
--client-out assets/coo/xl/data \
--client-format bin \
--server-out server/data \
--server-format json \
--files Item,Skill \
--version 2
Go CLI 参数同名同义，macOS（arm64 / x64）、Windows x64、Linux x64 都有预编译版本。
兼容性
- Cocos Creator 3.x，最低 3.0.0。
- 运行时数据目标，Web、Native（Android、iOS）。
实际数据长什么样
100 行、16 字段的同一份数据，左边是 Excel 源表，右边是游戏内读取结果，float、list、dict 都能对上。
链接
- 商品页 coo-xl-maker
- 反馈 QQ 99755349，也可以直接在本帖下面回