Cocos Creator 项目配置 JSON 最佳实践

在 Cocos Creator 里，用 JSON 做项目配置是最常见的一种方式。

不管是 UI 布局、玩法参数、表数据，还是一些简单的开关，都可以用 JSON 来管理。

如果项目越做越大，JSON 越堆越多，但写法不统一、目录不清晰、格式不一致，很容易影响维护。

下面我把自己在做 Creator 项目时整理的一些 JSON 使用习惯写下来，算是一个比较通用的最佳实践。

1. 配置文件放哪里比较合适？

我一般统一放在：

复制代码

assets/resources/config/

原因有两个：

resources/ 下面的东西可以在运行时用 cc.resources.load() 来动态加载
引擎对 JSON 文件有天然支持，加载也快

如果项目很大，我会继续拆：

复制代码

assets/resources/config/
    ui/
    audio/
    game/
    table/

好处是新来的同事也能大概猜到每类 JSON 是干什么的。

2. 配置文件的命名保持统一风格

我比较常用的命名方式是：
小写 + 下划线

例如：

复制代码

ui_config.json
audio_map.json
game_rule.json
level_table.json

统一命名的好处是：

搜索方便
脑子里一眼就知道用途
和脚本生成器更好对接（如果你有 PHP/Node 的自动生成工具）

避免用这种：

UIConfig.json
GameConfig2.json
Config-final-2022.json
abc.json（看不懂）

3. JSON 文件尽量保持"扁平化结构"

JSON 里结构越深，越不好维护，比如这种：

复制代码

{
    "ui": {
        "login": {
            "layout": {
                "pos": {
                    "x": 100,
                    "y": 200
                }
            }
        }
    }
}

在 Creator 工程里要取值非常麻烦：

复制代码

cfg.ui.login.layout.pos.x

一般建议控制结构深度，不超过三层。

如果层数太深，代表你把 UI 布局当成场景编辑器用，这不太合适。

4. 配置文件尽量只放"数据"，不要放"逻辑信息"

比如下面这种属于"逻辑信息"：

复制代码

{
    "btn_close": {
        "need_confirm": true
    }
}

因为"需不需要二次确认"这个概念很明显是逻辑层的判断。

配置里最好只存这种：

复制代码

{
    "btn_close": {
        "sound": "ui_click",
        "x": 100,
        "y": 200
    }
}

也就是说，配置负责告诉程序某个东西的参数，但不负责决定业务逻辑。

5. JSON 文件内的 key 建议采用统一命名

常用的命名习惯有两种：

写法 1：小写 + 下划线

复制代码

max_count
item_list
reward_type

写法 2：驼峰

复制代码

maxCount
itemList
rewardType

不要两种掺着来，更不要出现：

max_count_list_json_data
item-lower-list
ITEMLIST

最好一开始就定一个写法，整个组照这个写。

6. JSON 文件内容最好格式化，不要压缩存储

很多老项目里会出现这种：

复制代码

{"name":"xxx","type":1,"level":10,"list":[1,2,3]}

压缩存储没意义，Creator 对 JSON 加载速度本来就很快。

可读性才是最重要的。

建议格式化成：

复制代码

{
    "name": "xxx",
    "type": 1,
    "level": 10,
    "list": [1, 2, 3]
}

你之后查问题、找 key、合并配置的时候都会轻松不少。

7. 对于经常使用的 JSON，建议做一层缓存

Creator 每次从 resources/ 加载 JSON，都会进行一次解析。

如果在游戏运行过程中频繁加载，就会有一点消耗。

通常我会写一个简单的 ConfigManager：

复制代码

export class ConfigManager {
    private static _cache: Record<string, any> = {};

    static async load(path: string) {
        if (this._cache[path]) {
            return this._cache[path];
        }
        const data = await cc.resources.load(path, cc.JsonAsset);
        this._cache[path] = data.json;
        return this._cache[path];
    }
}

使用方式：

复制代码

const cfg = await ConfigManager.load("config/ui_config");

上层逻辑不需要关心加载细节。

8. 最好配一份"可读性更强的表"

比如策划给你的是 Excel，把它转成 JSON 后可能会长这样：

复制代码

[
    { "id": 1, "name": "A", "rate": 100 },
    { "id": 2, "name": "B", "rate": 50 },
    { "id": 3, "name": "C", "rate": 20 }
]

但是开发时读起来不方便，可以自动生成一份字典结构：

复制代码

{
    "1": { "name": "A", "rate": 100 },
    "2": { "name": "B", "rate": 50 },
    "3": { "name": "C", "rate": 20 }
}

优点是：

根据 id 查找快
业务层更好用
避免反复遍历数组

这个可以通过简单 Node 脚本生成。

9. 配置文件不要写注释（JSON 不支持）

很多人会在 JSON 里写注释，比如：

复制代码

{
    // 玩家等级
    "level": 10
}

Creator 在解析时也许能过，有些情况下会直接报错。

如果要写说明，可以考虑：

在旁边再放一个 .md 文档
写在 .ts 的注释里
写到工具生成器里

尽量不要在 JSON 里加。

10. 配合 Git，配置文件一定要可 diff

diff 最怕看到：

复制代码

全文件改动
每行都变色
顺序整个乱了

所以建议：

避免 key 自动排序
不要用代码工具重新生成"顺序不稳定的 JSON"
手改时确保结构不被破坏

这样 Git 在比较版本时更清晰。

小结

Cocos Creator 项目里的 JSON 配置，做到下面这几点就基本够用了：

放在统一目录，方便加载
命名统一
结构不要太深
配置不包含逻辑
格式化存储，不压缩
带缓存的加载方式
表数据可生成字典结构
避免在 JSON 内写注释
保证 diff 清晰，避免大面积自动格式化

这些习惯看起来简单，但在中大型项目里能省很多事。