Cocos Creator 项目配置 JSON 最佳实践

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

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

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

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

---

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

我一般统一放在：

assets/resources/config/

原因有两个：

1. resources/ 下面的东西可以在运行时用 cc.resources.load() 来动态加载

2. 引擎对 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 配置，做到下面这几点就基本够用了：

1. 放在统一目录，方便加载

2. 命名统一

3. 结构不要太深

4. 配置不包含逻辑

5. 格式化存储，不压缩

6. 带缓存的加载方式

7. 表数据可生成字典结构

8. 避免在 JSON 内写注释

9. 保证 diff 清晰，避免大面积自动格式化

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