我平时工作接触的东西比较杂。虽然是游戏开发，但用到的工具其实不少：Android 打包要用 Java，平时写脚本会用 Python 或者 JavaScript，还要维护项目的 GM 后台前端。
关键是不同项目依赖的版本还可能不一样。从 GitHub 上 clone 下来的项目，因为环境版本不对出现 bug 的情况，我也遇到过不少次。
以前我分别用 nvm、pyenv 和 jenv 管理这些版本，单独使用也没觉得有什么大问题。
直到最近整理了一下系统环境，这个问题就暴露出来了：.zshrc 里 Node 一套初始化，Python 一套初始化，Java 又是一套初始化。三个工具各管各的，命令不一样，配置位置不一样，出了问题还得分别排查。
说实话，不是 nvm、pyenv、jenv 不好用。单独拿出来，它们都能把自己的事情做好。真正让我难受的是：为了管理三个运行时，我也得同时管理三套版本管理工具。
所以我就搜了一下有没有开源工具能把这些事情统一起来，结果找到了 mise 官网 和 GitHub 仓库。截至 2026 年 8 月，GitHub 上已经有 33.1K Star。
这次我干脆全部换成了 mise。用了几天之后，我的感觉是：这种工具就应该统一啊，GitHub 真是一个宝库。
自己一个人开发时，版本不一致还不算特别明显。机器上默认是什么版本，项目通常就先用什么版本，遇到问题再切一下。
团队开发就不一样了。
同一份代码，在我电脑上能跑，到同事电脑上突然报一个莫名其妙的错。查半天业务逻辑，最后发现一个人用 Node 20，另一个人用 Node 22；或者 Python 的小版本不同，某个依赖装出来的结果不一样；再或者 Android 项目要求 JDK 17，某台机器的 JAVA_HOME 还指向 JDK 11。
这种 bug 最恶心的地方，是它看起来像代码问题，实际上是环境问题。
大家在群里说一句“这个项目要用 Node 20”没什么用，README 里写一遍也不保险。真正可靠的方式，是把工具版本和代码放在一起，让项目自己声明：我到底需要什么环境。
这正是 mise 最打动我的地方。
可以先把 mise 理解成一个开发工具版本管理器。
以前是：
nvmpyenvjenv现在是：
Node.js ─┐
Python ─┼─> mise
Java ─┘
而且它不只管这三种。Go、Ruby、Rust、Terraform、各种 npm、pipx、GitHub Release 里的 CLI 工具，也都可以放进同一套配置里管理。
当然，我目前真正高频使用的还是 Node.js、Python，所以这篇只聊我实际用到的部分，不拿“支持上千种工具”这种数字凑功能表。
.zshrc 终于清净了我在 Mac 上通过 Homebrew 安装：
brew install mise
然后在 .zshrc 里激活：
eval "$(mise activate zsh)"
重新打开终端后，可以跑一下：
mise doctor
以前为了三个版本管理工具，要分别初始化、分别处理 PATH 和环境变量。现在核心配置只剩这一份。
这一点听起来不算什么大功能，但迁移过一次电脑就知道有多舒服。以后换机器，我不用再回忆 nvm 怎么装、pyenv 还缺哪些编译依赖、jenv 的初始化顺序应该放在哪。先装 mise，再交给它统一处理就行。
平时总得有一套默认环境，可以直接这样配置：
mise use --global node@x.x.x python@x.x.x java@x.x.x
这条命令会安装对应工具 (版本号换成自己用的)，并把它们写进 mise 的全局配置。之后在没有项目级配置的目录里，就使用这套默认版本。
检查当前环境也很直接：
node --version
python --version
java --version
echo $JAVA_HOME
全局版本只是基础，mise 真正解决团队问题的，是项目里的 mise.toml。
比如进入一个项目后执行：
mise use node@22.14.0 python@3.12.9 java@22.0.0
mise 会在当前目录创建或更新 mise.toml：
[tools]
node = "22.14.0"
python = "3.12.9"
java = "22.0.0"
把这个文件提交到 Git，工具版本就不再是某个人电脑里的隐形配置，而是项目的一部分。
团队成员拉下代码后，执行：
mise install
需要的版本就会按项目配置安装好。进入这个目录，终端自动使用项目指定的 Node.js、Python 和 Java；离开目录，又恢复到全局默认版本或者另一个项目的版本。
整个切换过程不需要我手动执行 nvm use、pyenv local 或者再改一次 JAVA_HOME。这几天在 Mac 上用下来，目录切换基本没什么存在感，很丝滑。
我觉得这才是版本管理工具该有的状态：平时感觉不到它，只有环境不对时才意识到它替你挡掉了一个坑。
以前 Python 需要一个 .python-version，Node.js 需要一个 .nvmrc，现在一份 mise.toml 就能搞定。
我平时经常会临时写个脚本、验证一个想法。这种小东西可能今天用 Node，明天用 Python，过几天自己都忘了当时是什么版本。
以前通常懒得专门配置，直接拿全局版本跑。几个月之后再打开，突然跑不起来了，还得猜当时到底用了什么环境。
现在即使只是个小目录，也可以顺手执行：
mise use node@22
多一个很小的 mise.toml，换来的是这个目录以后随时打开都知道该用什么版本。这个习惯对“大项目”当然有用，但我觉得它对那些生命周期不确定的小工具更有价值。
如果只是临时跑一次，连配置文件都不想创建，也可以这样：
mise exec python@3.12 -- python script.py
它会在指定的 Python 环境里执行脚本，不需要先把全局版本切来切去。
我一开始只是想用 mise 替代 nvm、pyenv 和 jenv，但它实际上还可以管理项目环境变量和任务。
比如：
[tools]
node = "22.14.0"
[env]
NODE_ENV = "development"
[tasks]
dev = "npm run dev"
build = "npm run build"
之后可以统一执行：
mise run dev
mise run build
这样工具版本、环境变量和常用命令都放在一个文件里。新同事接手项目时，不需要先看半天文档，再手动拼出一套本地环境。
不过我现在没有急着把所有脚本都迁进去。版本管理已经解决了我最主要的问题，任务和环境变量准备后面按项目需要慢慢用。工具功能多不代表必须一次全上，先解决真实痛点更重要。
脑子里不用再记三套命令。想装版本、切版本、看当前版本，全部先找 mise。
工具一多，统一入口带来的不是少打几条命令，而是少了一整套上下文切换。
口头约定和 README 都会过期，配置文件才是能执行的约定。
只要团队统一安装 mise，拉代码后就能得到相同的运行时版本。它不可能消灭所有“我这里能跑”的问题，但至少能先把 Node、Python、Java 版本不同这一大类问题排除掉。
以前重装系统，需要分别安装 nvm、pyenv、jenv 和 JDK，再用不同的方式恢复各个项目需要的版本。现在只需要先装 mise，剩下的工具配置都能从全局配置和各项目的 mise.toml 恢复。
对于我这种今天写 TypeScript、明天跑 Python、后天又要打 Android 包的人，这种统一感比单项功能多强大更重要。
为了确认是不是刚换工具带来的新鲜感，我又看了几篇其他开发者的长期使用评测。
不过评价也不全是夸。在一篇 [Reddit 讨论]: https://www.reddit.com/r/webdev/comments/1hiripn/anybody_have_experience_with_mise_considering_it/ 里，比较集中的问题有两个：一是 VS Code 等从桌面启动的 IDE 有时拿不到终端里的 PATH，需要单独处理；二是冷门工具依赖不同 backend，质量和稳定性不一定像 Node.js、Python、Java 这些内置核心工具一样稳定。也有人对部分版本升级时的行为变化有意见。
所以我的判断没变：如果主要管理 Node.js、Python、Java 这类常用工具，mise 已经很好用了；如果项目依赖比较冷门的 SDK 或插件，先在自己的环境里完整跑一遍安装、切换和 CI，再决定要不要全团队迁移。
mise 也不是装完就能让所有软件自动理解你的环境，有几个边界最好提前知道。
第一，终端切换成功，不代表已经打开的 IDE 也会立刻切换。
Java 版本变化后，依赖 JAVA_HOME 的 IDE 可能需要重启。Android Studio 自己也有 Gradle JDK 配置，Gradle Daemon 还可能继续使用之前启动时的 Java。终端里 java --version 正确，只能证明当前终端正确，打包前最好再确认一下 Gradle 实际用了哪个 JDK。
第二，只使用 shims 时，部分环境变量能力不完整。
例如 Java 的 JAVA_HOME 需要 mise activate、mise exec 或 mise run 提供完整环境，不能只看到 java 命令能运行就以为全部配置好了。交互式终端我更推荐按官方方式完整激活；CI 和脚本里则可以显式使用 mise exec 或 mise run。
第三，陌生项目的配置别无脑信任。（项目配置是可以执行行为的, 这里可能会有恶意代码注入 或者 信息泄露风险，需谨慎）
别人提交的 mise.toml 如果包含环境指令、Hook 或任务，可能执行项目定义的命令，存在恶意代码执行或信息泄露风险。mise 遇到未信任的配置时可能会提示 mise trust，但也不要把这行提示当成唯一的安全检查：当前普通模式下，mise install、mise run、mise exec 等显式执行项目行为的命令会自动信任当前配置。网上随便拉下来的仓库，先看看配置写了什么，再执行这些命令。
第四，旧版本文件的兼容要自己确认。
mise 可以识别 .nvmrc、.python-version、.java-version 这类已有文件，但目前这些“惯用版本文件”默认并不是全部自动启用。如果正在迁移老项目，不要看到文件还在就默认 mise 一定读取了，先用 mise config ls 和实际版本确认一下。我的选择是新项目统一使用 mise.toml，规则更直观。
mise 官方支持 Windows 和 PowerShell，Node.js、Python 等核心后端也提供 Windows 支持。官方文档还专门处理了 Windows 下 Python 可执行文件和 pip 包装脚本的问题。
因为我手上没有 Windows 设备，没有真实跑过安装、自动切换、PowerShell 激活和 IDE 集成，不清楚是否和 Mac 上体验一样丝滑。
Mac 上这几天的体验我可以负责：安装简单，切目录很顺，Node.js、Python、Java 放在一起管理之后，整个开发环境清爽了很多。Windows 到底有没有路径、权限或者终端兼容方面的小坑，还是得实际用过才知道。
下面这些基本覆盖了我日常管理 Node.js、Python 和 Java 的场景。命令里的 x.x.x 换成实际版本号。
# 安装 mise
brew install mise
# 安装后把这一行加入 .zshrc，重新打开终端生效
eval "$(mise activate zsh)"
# 查看当前生效版本
mise current
mise current node
mise ls
# 查看远端可安装版本
mise ls-remote java
mise ls-remote node
mise ls-remote python
# 设置全局默认版本
mise use --global python@x.x.x
mise use --global node@x.x.x
mise use --global java@x.x.x
# 为当前项目设置版本，同时写入当前目录的 mise.toml
mise use python@x.x.x
mise use node@x.x.x
mise use java@x.x.x
# 安装当前项目 mise.toml 中声明的全部工具
mise install
# 临时切换当前终端的版本
mise shell java@x.x.x
# 查看当前实际执行的命令，以及对应工具的安装目录
mise which node
mise where node
# 检查可更新项并升级
mise outdated
mise upgrade
# 仅安装指定版本，不写入 mise.toml，也不切换当前版本
mise install python@x.x.x
mise install node@x.x.x
# 卸载指定的已安装版本
mise uninstall node@x.x.x
# 环境诊断
mise doctor
这里有几个容易搞混的地方：
mise use 是“安装并使用”，还会把版本写入全局配置或当前项目的 mise.toml；mise install 只是安装。后面带版本号时不会自动写配置，也不会让这个版本立即生效；不带参数时则安装当前配置声明的全部工具；mise shell 只影响当前终端，而且要求当前 shell 已经执行过 mise activate；关闭终端后这次切换就没了；mise upgrade 默认只在配置允许的版本范围内升级。如果 mise.toml 写死了完整版本号，想升级并改写配置，需要先看 mise outdated --bump，再执行 mise upgrade --bump；mise uninstall 只删除本机安装的工具版本，不会删除 mise.toml 里的配置。如果项目仍然引用这个版本，下次执行 mise install 还会重新装回来。如果你只写一种语言，而且现有的 nvm 或 pyenv 已经用得很舒服，完全没必要为了追新工具专门折腾。mise 最大的价值，不是它把某一种语言管理得比所有专用工具都强，而是它能用同一种方式管理很多工具。
如果你和我一样：
.zshrc 里塞了好几套版本管理工具的初始化；那 mise 很值得试一下。
我目前的评价很简单：它没有发明版本管理这件事，只是终于把散落在各个语言里的版本管理，收进了同一个工具。
用了几天之后，我已经不太想回到 nvm、pyenv、jenv 各管一摊的状态了。
之前做的一款游戏，上线运营都两年了，然后老板一句话：这游戏要发海外。
当时直接懵逼了。
那个项目里不止有超级多的硬编码中文，还有各种拼接出来的中文字符串，外加超级多带文字的图。界面设计的时候压根没考虑过多语言，文本框就那么点大，英文塞进去直接溢出。这种情况没有任何取巧的办法，只能把所有文本全部翻一遍、逐个硬找。幸亏现在有 AI，让 AI 先快速过一遍把文本全扒出来，再人工一条条处理，不然纯靠人肉翻代码，工期根本不敢想。
所以，以后设计游戏架构，得把多语言提前考虑进去。不一定用得上，但是万一哪天老板又来一句”发海外”，至少不用再经历一遍这种痛苦。
所以就有了下面这套东西。先说明，这不是什么业界标准方案，纯野路子——我自己琢磨出来的一种”既方便后期转多语言，又基本不影响日常开发”的适配方式。
先说明一下范围：下面主要讲的是代码里硬编码文本怎么处理，带文字的图和界面布局这两个坑不好用同一套办法解决，放到最后简单聊聊。
有一个前提：硬编码文本还是尽量写中文。毕竟是中国人，显示界面中的文本写个中文看起来多顺眼。如果为了多语言，日常开发全写 I18n.get("ui_btn_confirm") 这种 key，对于我这种英语不太好的人来说，看不懂啊，难受啊。所以我的目标是：平时写代码就当没有多语言这回事，只在需要的时候能够快速支持其他语言。
下面就讲讲具体是怎么做
多语言最常见的做法是”文案表”：代码里只写 key，运行时拿 key 查表得到当前语言的文案。问题在于 key 是要人来起的，一句”确定”你得先想好它叫 common_ok 还是 dialog_confirm，再去表里登记，写代码的节奏就被打断了。
我的做法是把 key 分成两层。
分之前先说一个中文特有的坑：同一个中文词，在不同语境下翻译可能完全不同。比如”装备”，作名词是背包里的装备，英文是 equipment；作动词是把装备穿上，英文是 equip。如果两处都直接写中文，就只能共用一条译文，必有一处译错。这种词必须起独立的 key、分开翻译——这就是常量层存在的核心原因之一。
第一层：常量 key。短词、会被多处复用的文案 或者 相同的中文但是需要不同的翻译文本的，在 TextKey.ts 里集中定义：
/**
* 简中文案表 属性名即key 值即中文 新增文案在这里加一行
* 本表同时就是简中语言的文案表 所以简中不需要加载任何资源
*/
export const ZH_TEXTS = {
/********** 通用 **********/
common_ok: "确定",
common_cancel: "取消",
common_close: "关闭"
} as const;
用的时候 I18n.get(TK.common_ok)，有 IDE 补全，key 拼错了 TS 编译直接报错。
第二层：中文原文本身就是 key。只出现一次的长句，根本不起 key，直接把中文传进去：
ui.WindowManager.showWindow(Alert, {
title: I18n.get("更新提示"),
content: I18n.get("检测到{mb}MB的更新资源, 是否更新？", { mb: result.size / 1024 }),
okTitle: I18n.get("更新"),
cancelTitle: I18n.get("退出游戏")
});
写起来跟硬编码几乎没有区别，只是外面套了一层 I18n.get()。查表的时候 key 就是这句中文本身，查不到就直接返回 key——反正 key 就是原文。
这一层，图的就是省事：写这句话的时候完全不用想”这个 key 该叫什么、该去哪个文件加一行”，写完中文往外面套一层函数就完事，不用跳出去改配置文件。
两层的分工很简单：短词、复用的走常量；一次性的长句直接用中文。什么时候该把中文提成常量，交给检查工具去提醒（后面讲），开发的时候不用纠结。
这套设计里我最满意的一点是：简体中文不需要任何额外资源。
ZH_TEXTS 这张表本身就是简中的文案表，初始化时直接灌进内存；中文原文 key 更省事，查不到表就返回 key 本身，天然就是正确文案：
public static init(lang: Language): void {
this._lang = lang;
this._texts.clear();
if (lang === Language.ZH) {
// 简中直接拿 ZH_TEXTS 当文案表 不读任何资源
const texts: Readonly<Record<string, string>> = ZH_TEXTS;
for (const key of Object.keys(texts)) {
this._texts.set(key, texts[key]);
}
} else {
this.loadTexts(lang);
}
}
只有非中文语言，才去加载对应语言的文案表 json（按语言分 bundle，language-en/hardcode.json 这种）：
const language = LanguageHelper.language;
if (language !== Language.ZH) {
// 加载对应语言的文件, 方便之后使用
}
也就是说，只要这个项目不出海，多语言这一整套东西对包体、对加载流程、对运行时性能、对平常开发的便捷程度的影响几乎都是零。这就是我说的”不影响日常开发”。
回到开头那个老项目，最要命的其实不是硬编码多——硬编码再多吃苦也能翻完。真正折磨人的是拼接字符串：
// 反面教材
text = "恭喜你获得了" + count + "个" + itemName;
这种句子没法整体进文案表，因为变量部分的取值无法穷举。更要命的是语言之间的语序不一样，中文”获得了3个金币”，英文是 “Obtained 3 gold coins”，”个”这种量词在英文里根本不存在，按词拆开翻译再拼接，拼出来全是病句。
所以这套方案里，动态内容统一用 {name} 占位符：
I18n.get("检测到{mb}MB的更新资源, 是否更新？", { mb: size });
整句进文案表，翻译可以看到完整语境，变量位置随便挪。
那有人非要写拼接怎么办？靠自觉是不行的，得靠工具拦。
光靠自觉是不够的，得有工具拦一下。我写了几个脚本放在 tools/i18n/ 下，核心是用 TypeScript Compiler API 做 AST 扫描——比正则靠谱，能准确分清参数到底是字符串字面量、TK.xxx 常量引用，还是拼出来的模板串。
脚本主要干两件事：
ZH_TEXTS 的全部条目、加上代码里所有 I18n.get("中文…") 的字面量，合并成一份 json，丢给翻译或者 AI 去翻，翻完回填到对应语言的文案表；+ 拼接的写法，拦掉”某句中文已经在 ZH_TEXTS 里定义过又被人以原文重复写了一遍”的情况，顺带提醒哪些中文重复出现太多次该提成常量了。导出的 json 具体怎么用，再说细一点： 翻译同学或者策划不一定爱看 json，这块可以再写个工具把这份数据转成 Excel、CSV 或者任何他们习惯用的格式——具体导出成什么样、字段怎么排，看自己团队的需求，这种转换脚本 AI 写起来也很顺手。
这几个脚本具体怎么写我就不展开了——这种活儿现在直接丢给 AI 写就行，把规则讲清楚，AST 怎么解析、判断逻辑怎么写，AI 都能给你搞出来。写完之后接进 pre-commit，提交前跑一下增量检查，写错了当场打回；CI 上再跑一次全量扫描保底就好了。
说实话，它只覆盖了”代码里的文本”，老项目里另外两个坑它管不了：
另外这套扫描只覆盖代码，FGUI 编辑器里直接填的静态文本也在射程之外，项目里的约定是：界面文本统一走代码赋值，FGUI 里只放占位——这条约定本身也是为了方便扫描。
整套东西说白了就是想解决一个问题：开发的时候压根不想惦记多语言这回事，能不能等真要出海了再一次性搞定。
{name} 占位符，让翻译看到整句；日常开发的体验几乎没有变化——写中文、正常提交，唯一的额外动作是偶尔多套一层 I18n.get()。但如果哪天真要出海，跑一次导出脚本，所有需要翻译的文案就整整齐齐躺在一份 json 里了。
这只是我自己琢磨出来的一个野路子，肯定不是什么标准答案，带文字的图和界面布局那两块也还有很多细节没讲透，有更好的方式欢迎交流讨论。核心思路就一条：日常开发的时候，脑子里只装中文就够了。
]]>这本书我真的是读过5遍以上了，每次看还都能有一些收获，这本书究竟讲了些什么呢？他不讲数据结构，不讲语法，只说了代码怎么写好维护。下面听老宫展开讲讲吧
全书我记得最牢的一句话，反而不是哪条具体规则，是那句童子军军规：离开营地时，让它比你来的时候更干净。
以前改一个 bug，顺手改完就走，绝不多碰一行——生怕改多了引入新问题，也没那个心思。现在心态变了：改到哪块代码，只要顺路，看到一个命名很烂就顺手改了，看到一段重复逻辑就顺手提出来。不是刻意去做”重构任务”，就是路过的时候擦一下灰。这个习惯坚持了几个月，明显感觉到自己维护的几个模块比以前顺眼多了（不过这里又违背了开闭原则）
书里讲命名那一章，说实话道理都不新鲜，但我读的时候是确实有点羞耻。data、info、temp、flag，这些词我写代码的时候用得飞起，图省事，反正自己知道是什么意思。
问题是三个月之后我自己都不知道那个 flag 到底控制的是什么。后来养成一个习惯：写变量名的时候，多花两秒问自己一句”如果这行代码脱离上下文单独拿出来，我还能看懂吗”。答不上来就换个名字。布尔变量尤其如此，isXxx、hasXxx 这种前缀，看着啰嗦，但比 flag 强一百倍。
魔法数字也是，之前写超时时间直接写 3600，谁看了都得反应半天是不是一小时。现在起码会给它起个名字，哪怕只是个局部常量。
“函数只做一件事”这句话听起来像句正确的空话，谁都会说。真正让我改主意的是书里那个判断标准：如果你能从这段代码里再拆出一个函数、并且新函数的名字不是对原函数的简单重复，那说明原函数确实干了不止一件事。
这个标准比”多少行以内”实用多了。我以前写一个处理流程，习惯把校验、算钱、存库、发通知全堆在一个函数里，中间穿插着注释分段。看着挺整齐，其实就是偷懒。现在这种活会拆成好几个小函数，主函数读起来跟看目录一样：
function register(user: User): void {
validate(user);
applyDiscount(user);
persist(user);
notify(user);
}
拆完之后有个意外的好处：写单测方便多了。以前那种大杂烩函数，写测试的时候要构造一堆前置条件才能覆盖到中间某一步，现在每个小函数单独测，轻松很多。
参数个数那条我倒是没完全照做，书里说超过两三个参数就该封装成对象，道理对，但很多时候懒得为一个用一次的场景专门建个类。
我以前觉得注释多是负责任的表现，改完代码习惯性写一句”这里是干什么的”。看完这本书才意识到，这种注释基本等于承认代码没写清楚——如果命名和结构到位，代码本身就该讲清楚”做什么”，注释真正该干的事是解释”为什么”：为什么这里绕了个弯、为什么不能用更直接的写法。
过期注释更让人难受。我确实写过那种改了代码却没改注释的情况，后来的人（包括我自己）直接信了注释,结果被坑。看完这段之后，我现在宁可少写注释，也不留一句可能过期的说明。
被注释掉的死代码也一样，以前总舍不得删，”说不定以后用得上”，现在想开了，有版本控制记着呢，删就删。
这一章我看了两遍才真的转过弯。之前一直觉得”面向对象”就是把数据和方法包一起，写着写着就写出一堆四不像的类——公开一堆字段又挂几个方法，两头都不占。
书里说得很直接：对象应该隐藏数据、暴露行为；数据结构应该反过来，暴露数据、没有行为。
混着写，两边的好处都拿不到。这条思路帮我理清了不少之前设计不清楚的类，遇到只是拿来传数据的场景，我现在会大方地让它只是个数据结构，不硬塞方法进去。
得墨忒耳定律（最少知识原则）也是这章里让我印象深的，说白了就是别写 a.getB().getC().doSomething() 这种链式穿透。这种写法我以前写起来还挺顺手，觉得省事，现在看就是把内部结构暴露得一览无余，牵一发动全身。
用异常代替返回码这条我一直是认同的，倒不算新知识。真正让我改变做法的是”别返回 null，也别传 null”这条。
我以前写方法，查不到东西习惯性 return null，调用的地方各自加判断。问题是总有人忘了判断，NullPointerException 就是这么来的，而且往往炸在离出错原因很远的地方，排查半天。现在会尽量返回空对象或者直接抛异常，让调用方不用猜”这里会不会是 null”。
以前对单测的态度是”知道该写，但总没时间”。这本书没有讲什么新道理，但那句”测试代码和生产代码同等重要”这句话，配合前面函数拆小的习惯一起看，让我真正觉得写测试这件事门槛低了很多——函数一旦拆小、职责单一，测试自然就好写了，不再是一件额外的苦活。
有一章特别短，短到我第一次读的时候几乎没留下印象，当成过渡章节就翻过去了。后来才反应过来，Kent Beck 那套”简单设计四规则”其实到处都有人引用，只是我当时没往心里去。
四条规则，是按优先级排的：
一开始看这四条觉得又是正确的空话，后来发现顺序才是关键：第一条摆在最前面，意思是先把测试跑通、把行为锁死，剩下三条才是在测试保护下才敢动手做的事——没有测试兜底,谁敢一边重构一边保证没改坏东西。
第二、第三条我平时不知不觉就在做，重复代码看到就想提取，命名不清楚就想改，这些跟前面几章讲的其实是一回事。真正让我多想了一下的是第四条,”尽量减少类和方法的数量”和第一章那种”拆函数、拆类”的建议摆在一起看，其实是有张力的：拆得太狠，元素一多，理解成本也上去了。书里把它排在最后，意思也很明白——先满足前三条,元素数量才是最后才该权衡的事,不能为了少写几个类,反过来牺牲表达力和去重。
这本书也不是每条都让我心服口服。比如格式那一章讲垂直对齐、水平间距的一些细节，现在基本都靠 formatter 自动搞定了，专门花心思去手动对齐感觉意义不大。系统与并发那一章讲得比较抽象，看完印象不深，可能是我自己实际接触并发场景不算多，共鸣有限。
坏味道那一章列的清单挺实用，但说实话看完没记住几条具体名字，更多是变成了一种”看到重复代码/长函数/多参数就浑身不舒服”的直觉，具体叫什么”坏味道”倒没那么重要。
这本书对我最大的作用，不是教会我什么新概念——里面大部分道理，稍微写过几年代码的人多少都听过。它真正做的是把这些散落的常识，用一套具体、可执行的判断标准串起来，逼着你去对照自己写的代码,一条一条地脸红。
如果只让我留一句话提醒自己，还是那句童子军军规：离开时，比来的时候更干净一点就够了。不用等一个”重构专项”，也不用等”有空的时候”，就是这一次改动，顺手做一点。
]]>我之前维护过一个叫 kunpocc 的框架，UI 管理、平台适配、计时器、条件系统等功能全塞在一个包里。刚开始用着挺爽，装一个包什么都有。但用久了问题就冒出来了：
有的项目只想要个网络库，结果因为依赖了 kunpocc 主包，把 UI 系统、热更新那一堆代码也一起打进去了。想升级某个模块的一个小 bug，整个框架的版本号跟着往上跳，其他没改动的功能也要跟着走一遍回归测试。想单独维护 ECS 这部分逻辑，翻源码的时候还要绕开一堆不相关的目录。
说白了，单体框架在项目小的时候是效率，项目一多、维护周期一长，就变成了负担。所以这次没有缝缝补补，直接推翻重做：bit-framework，一个 pnpm Monorepo，把原来揉在一起的功能拆成 12 个完全独立的包，各自发版本、各自管依赖，你的项目需要什么就装什么。
bit-framework 是基于 Cocos Creator 3.x 的游戏开发框架集合，用 pnpm workspace 统一管理源码，但每个模块单独发到 npm，命名空间是 @gongxh/bit-xxx。12 个模块按功能分成 5 类：
| 分类 | 模块 | 一句话 |
|---|---|---|
| 核心 | bit-core | 时间、定时器、平台检测、屏幕适配等基础工具 |
| UI | bit-ui | 基于 FairyGUI 的窗口管理系统 |
| UI | bit-condition | 条件显示系统，做红点、解锁提示 |
| 游戏架构 | bit-ecs | 高性能 ECS 架构 |
| 游戏架构 | bit-ec | 面向 Cocos 场景的轻量 EC 架构 |
| 游戏架构 | bit-event | 全局事件系统 |
| 网络与资源 | bit-net | HTTP + WebSocket 跨平台网络库 |
| 网络与资源 | bit-assets | 资源加载管理，按批次卸载 |
| 网络与资源 | bit-hotupdate | 热更新系统封装 |
| 工具 | bit-quadtree | 四叉树空间索引，做碰撞检测 |
| 工具 | bit-behaviortree | 行为树，做游戏 AI |
| 工具 | bit-minigame | 微信/支付宝/字节跳动小游戏平台适配 |
每个模块都可以单独安装、单独使用，互相之间没有强制绑定。
拆模块最容易踩的坑是拆着拆着又变成一堆互相纠缠的小单体，所以这次定了几条硬规矩：
单向依赖，禁止循环。模块之间只允许单向引用，比如 bit-ui 依赖 bit-core，但 bit-core 绝对不会反过来依赖 bit-ui。真的需要双向通信的场景（比如 UI 层要感知业务层的状态变化），走 bit-event 广播，不走模块间直接调用。
该依赖的东西交给 peer dependency，由使用方的项目自己装，保证全项目只有一份实例。比如 bit-ui 需要 bit-core 和 @gongxh/fairygui-cc，但这两个包不会被 bit-ui 自己打进去，而是声明成 peer 依赖：
npm install @gongxh/bit-ui @gongxh/bit-core @gongxh/fairygui-cc
依赖关系整体是这样的：
bit-core ←── bit-ui / bit-condition / bit-minigame / bit-hotupdate
bit-net ←── bit-hotupdate
bit-event ←── bit-ec
bit-ecs / bit-assets / bit-quadtree / bit-behaviortree 完全独立，零依赖
也就是说，如果你只想要一个四叉树碰撞检测，或者只想要个行为树做 AI，装一个包就够了，不会因此把整套 UI 系统也带进项目。
方式一：在你的 Cocos Creator 项目里按需装（推荐）
# 只要核心工具
npm install @gongxh/bit-core
# UI 系统（peer 依赖要一起装）
npm install @gongxh/bit-ui @gongxh/bit-core @gongxh/fairygui-cc
# 一次装个常用组合
npm install @gongxh/bit-core @gongxh/bit-ui @gongxh/bit-event @gongxh/bit-net @gongxh/fairygui-cc
方式二：本地开发/参与贡献
git clone --recurse-submodules https://github.com/gongxh0901/bit-framework.git
cd bit-framework
pnpm install
pnpm build
用 pnpm 而不是 npm/yarn，主要是看中它的硬链接省磁盘、依赖管理更严格、原生支持 workspace，几个包一起改动的时候体验明显更顺。
TypeScript 5.x 开发，Rollup 打包，每个模块的 dist/ 下都会产出 ESM、CommonJS 和压缩版，外加完整的 .d.ts 类型定义。装饰器用得比较多（experimentalDecorators），UI、ECS、EC、条件系统都是靠装饰器注册类的。Cocos Creator 版本要求 3.7.0+，日常开发用的是 3.8.x。
这篇是全局导览，接下来会给每个模块单独写一篇，讲清楚它解决什么问题、核心 API 怎么用、有哪些坑要避开。如果你只关心某一块功能，可以直接跳过去看对应模块的文章。
（下面各模块文章中的仓库链接会指向对应子目录，方便直接跳转看源码。）
欢迎按需取用，也欢迎提 Issue 和 PR。
]]>写 Cocos Creator 游戏的时候，有一堆代码几乎每个项目都要写一遍：判断当前是不是微信小游戏、拿屏幕安全区做适配、搞个全局定时器管技能冷却、格式化一个倒计时文案……这些东西单独看都不难，但项目多了之后，同样的逻辑在不同项目里重复实现，风格还都不一样，改一次 bug 只改了一个项目，其他项目还带着老问题。
bit-core 就是把这些”每个项目都要写”的基础功能收拢到一个包里：时间处理、定时器、平台检测、屏幕适配、日志、常用数据结构。它是 bit-framework 里被依赖最多的模块，bit-ui、bit-condition、bit-minigame、bit-hotupdate 都把它当 peer 依赖。
npm install @gongxh/bit-core
不需要任何其他依赖，可以独立使用。
除了拿时间戳这种基础操作，比较实用的是内置了网络时间同步——很多游戏对本地时间不完全信任（怕玩家改系统时间作弊），可以把服务器时间同步进来做基准：
import { Time } from '@gongxh/bit-core';
Time.setNetTime(serverTimestamp); // 用服务器时间校正
Time.now(); // 之后拿到的都是校正后的时间
Time.getDayStartTime(); // 当天 0 点时间戳，结算日重置常用
Time.isSameDay(t1, t2); // 判断是否同一天
时长格式化这块也做了两种粒度：formatDuration 按你给的 pattern 精确格式化，formatSmart / formatSmartSimple 会自动隐藏为 0 的单位，适合倒计时文案不想手动拼接的场景。
游戏里散落的 setInterval/setTimeout 最容易出的问题是场景切换时忘记清理，导致回调打在已经销毁的对象上。GlobalTimer 统一管理，还支持暂停恢复：
import { GlobalTimer } from '@gongxh/bit-core';
// 每秒执行一次，无限重复
const timerId = GlobalTimer.startTimer(() => {
console.log('心跳');
}, 1, -1);
GlobalTimer.pauseTimer(timerId); // 比如切到后台时暂停
GlobalTimer.resumeTimer(timerId);
GlobalTimer.stopTimer(timerId);
小游戏平台一多，if-else 判断平台的代码到处都是。Platform 把这些判断收成一批只读属性：
import { Platform } from '@gongxh/bit-core';
if (Platform.isWX) {
// 微信小游戏
} else if (Platform.isNativeMobile) {
// 原生移动端（Android/iOS/HarmonyOS）
}
刘海屏、挖孔屏这些异形屏，安全区不处理好，UI 元素会被摄像头或者虚拟按键挡住。Screen 提供了拿到手就能用的安全区信息：
import { Screen } from '@gongxh/bit-core';
console.log(Screen.SafeWidth, Screen.SafeHeight); // 安全区宽高
console.log(Screen.SafeAreaTop, Screen.SafeAreaBottom); // 四边 inset
有个细节要注意：横屏因为没法区分设备是左手还是右手朝向，左右两侧的安全区会对称地都用 safeAreaTop 的配置值，不是分别计算。长边和短边比例小于等于 16:9 的设备（大多数平板），四边 inset 会直接清零，安全区等于全屏。
统一的日志输出，方便上线后统一关闭调试日志：
import { enableDebugMode, debug, warn, error } from '@gongxh/bit-core';
enableDebugMode(false); // 生产环境关掉 debug 级别日志
内置了二叉堆、链表、双向链表、栈，都是游戏开发里常会手写的东西，直接拿来用：
import { BinaryHeap } from '@gongxh/bit-core';
// 小顶堆，常用来做技能冷却队列、AI 决策优先级排序
const heap = new BinaryHeap<Task>((a, b) => a.priority - b.priority);
heap.push(task);
heap.pop();
如果你的项目习惯把游戏系统拆成一个个”模块”（背包模块、任务模块……），可以继承 Module 统一生命周期入口，实现 onInit() 就行，不用每个系统都自己定义一套初始化规范。
Screen 的安全区配置要在 CocosEntry 的 Inspector 面板里设，不是代码里传参数，容易漏配导致横屏适配不对。Time.setNetTime() 只是给个基准，之后 Time.now() 是基于这个基准 + 本地流逝时间计算的，不是每次都重新请求服务器，别指望它帮你做防作弊校验，真要防作弊还是得后端兜底。GlobalTimer 是全局单例，场景切换、组件销毁的时候记得手动 stopTimer，不然定时器会一直跑。如果你的项目需要 UI 管理（bit-ui）、条件显示（bit-condition）、小游戏适配（bit-minigame）或热更新（bit-hotupdate），这几个模块都是直接把 bit-core 当 peer 依赖用的，装它们的时候记得把 bit-core 也一起装上。
用 FairyGUI 做 UI 的项目，早晚都要自己写一套窗口管理：打开窗口要不要先关掉上一个、UI 资源什么时候加载什么时候释放、多个窗口叠在一起谁在最上层、切场景的时候一堆没关掉的窗口怎么清理干净。这些逻辑不是难，是琐碎，而且每个项目都要重新写一遍，还容易漏处理某个边界情况（比如窗口没显示完就被销毁，资源引用计数对不上）。
bit-ui 把这套窗口生命周期管理做成了现成的框架，你只要按装饰器的规则写窗口类，剩下资源加载、层级、多窗口组的事交给它。
bit-core 和 @gongxh/fairygui-cc 是 peer 依赖，要一起装，保证全项目只有一份实例：
npm install @gongxh/bit-ui @gongxh/bit-core @gongxh/fairygui-cc
窗口类继承 Window，用装饰器注册：
import { Window, _uidecorator } from '@gongxh/bit-ui';
const { uiclass, uiprop, uiclick } = _uidecorator;
@uiclass("Home", "MainWindow", "MainWindow")
export class MainWindow extends Window {
@uiprop private btnStart: GButton;
@uiprop private txtTitle: GTextField;
protected onShow(userdata?: any): void {
this.txtTitle.text = userdata?.title ?? '默认标题';
}
@uiclick
private onBtnStart(): void {
console.log('开始游戏');
}
}
uiclass 的三个参数分别是窗口组名称、FairyGUI 包名、组件名——组件名必须和类名完全一致，这是它能自动关联 FairyGUI 资源的关键，写错了会找不到对应组件。
import { WindowManager } from '@gongxh/bit-ui';
// 参数是窗口类本身，不是字符串名称
await WindowManager.showWindow(MainWindow, { title: '欢迎回来' });
WindowManager.closeWindow(MainWindow);
showWindow 是异步的，因为它内部要先把这个窗口对应的 FairyGUI 包加载进来，加载完了才创建、显示。如果打开窗口前还需要额外请求服务器数据（比如打开背包前先拉一次背包列表接口），可以用 beforeLoad，这段逻辑会在 UI 包加载前先执行完：
await WindowManager.showWindow(BagWindow, userdata, {
beforeLoad: async () => {
userdata.bagList = await requestBagList();
},
});
beforeLoad 执行期间会复用你配置的通用等待窗，不用自己再单独弹一个 loading。
打开新窗口时，WindowType 决定怎么处理原来在屏幕上的窗口：
Normal —— 不做任何处理，叠在上面CloseOne / HideOne —— 关闭/隐藏上一个窗口CloseAll / HideAll —— 关闭/隐藏所有窗口比如从主界面进副本界面，通常想把主界面隐藏而不是关闭（回来的时候能直接恢复状态），这时候用 HideOne，副本界面关闭后主界面会自动走 onShowFromHide() 生命周期恢复回来。
如果好几个窗口顶部都是同一条资源栏（金币、钻石、体力），没必要每个窗口都重复放一份，用 Header 基类单独定义一次，跨窗口复用：
import { Header, _uidecorator } from '@gongxh/bit-ui';
const { uiheader } = _uidecorator;
@uiheader("Common", "TopHeader")
export class TopHeader extends Header {
protected onShow(userdata?: any): void {
// 刷新金币、钻石显示
}
}
窗口用 AdapterType 决定怎么适配屏幕：
Full —— 全屏适配（默认，大部分窗口用这个）Bang —— 按 Screen（来自 bit-core）算出的安全区避让，窗口定位在安全区中心，适合异形屏上不想被摄像头/挖孔挡住的窗口Fixed —— 固定尺寸不适配，适合弹窗、提示框这类uiclass 第三个参数（组件名）必须和 TypeScript 类名一致，这是隐性约定，不遵守的话运行时会提示找不到组件，排查起来容易懵。showWindow 传的是窗口类本身（构造函数），不是窗口名字符串，跟很多其他 UI 框架的习惯不一样，容易写错。HideOne/HideAll 隐藏的窗口不会自动释放资源，只有 closeWindow 才会走完整的生命周期和资源回收，长期隐藏不用的窗口记得该关就关。需要红点、功能解锁提示这类跟 UI 联动的条件显示逻辑，可以配合 bit-condition 一起用。
红点系统看着简单，做起来烦。一个红点的显示条件可能是”有未读邮件”，另一个可能是”背包里有新装备 或者 有可升级的装备”，条件组合一多，代码里到处散落着 if (hasNewMail() || hasUpgradableItem()) 这种判断，而且数据一变还要记得手动去刷新对应的红点节点，漏刷新是最常见的红点 bug 来源。
bit-condition 把”判断条件”和”通知 UI 更新”这两件事拆开管理：你只管写条件类怎么判断，节点怎么显示交给框架，数据变化时通知框架重新算一遍，该显示的自动显示，该隐藏的自动隐藏。
bit-core 和 @gongxh/fairygui-cc 是 peer 依赖：
npm install @gongxh/bit-condition @gongxh/bit-core @gongxh/fairygui-cc
场景根节点或者一个常驻的管理节点上挂 ConditionModule 组件，它负责定时批量重算所有待更新的条件（默认 0.3 秒一次），不是每次数据变化就立刻算，攒一批一起处理，性能更友好：
// 挂在场景管理节点上，updateDeltaTime 可以在 Inspector 里调
先用枚举定义好有哪些条件类型，再继承 ConditionBase 实现判断逻辑：
import { _conditionDecorator, ConditionBase } from '@gongxh/bit-condition';
enum ConditionType {
NewMail,
UpgradableItem,
}
@_conditionDecorator.conditionClass(ConditionType.NewMail)
export class NewMailCondition extends ConditionBase {
protected onInit(): void {
// 这里可以注册数据变化的监听
}
protected evaluate(): boolean {
return MailSystem.hasUnreadMail();
}
}
evaluate() 只管返回布尔值，什么时候调用、调用完怎么通知节点，都不用你操心。
邮件系统收到新邮件时，找到条件实例调用 tryUpdate()，告诉框架”我这个条件可能变了，下个周期重新算一下”：
newMailCondition.tryUpdate();
ConditionAnyNode 和 ConditionAllNode 是内置的两种组合模式，分别对应”任一条件满足就显示”和”所有条件都满足才显示”：
import { ConditionAnyNode } from '@gongxh/bit-condition';
// 邮件红点：有未读邮件 或者 有可升级装备，任一满足就亮红点
const redDot = new ConditionAnyNode(redDotNode, ConditionType.NewMail, ConditionType.UpgradableItem);
节点销毁前记得调用 destroy() 解绑；如果是挂在 FairyGUI 对象上的 ConditionFGUINode，GObject.removeFromParent() 的时候会自动帮你解绑，不用手动处理。
ConditionMode 只有两种：
Any（0）—— 任意一个条件满足就算满足，红点、提示类场景最常用All（1）—— 所有条件都要满足，比如某个功能同时要求”等级达到10级”和”完成新手引导”才解锁如果 Any/All 都不够表达你的逻辑（比如条件之间还要加权重、或者要 A 且非 B），直接继承 ConditionBase 自己写一个组合条件类，evaluate() 里调用其他条件实例的结果自己拼逻辑就行，框架没有限制你必须用内置的两种模式。
evaluate() 不会自动被高频调用，只有调用过 tryUpdate() 之后，才会在下一个更新周期被重新计算。如果条件判断依赖的数据变了但忘了调 tryUpdate()，红点状态就会一直停留在旧值，这是最容易踩的坑。ConditionModule 只能挂一份在场景里生效，别指望多挂几个能加速刷新——批量定时更新本身就是为了避免频繁计算，加实例只会重复算,不会更快。跟 bit-ui 的窗口系统配合起来用效果最好，红点挂在窗口内的 FairyGUI 节点上，窗口关闭时节点自动跟着销毁解绑。
弹幕游戏、大型 RTS、需要同屏处理成百上千个单位的游戏，最容易被面向对象那一套写法拖垃：继承层级一深，一个”会飞的会打的会加血的怪”到底该继承哪个基类就能吵半天，而且对象越多，遍历判断类型的开销越大，GC 也跟着遭罪。
ECS（实体-组件-系统）架构把”是什么”（组件，纯数据）和”做什么”（系统，纯逻辑）拆开，实体只是个数字 ID，靠组件的组合决定它的行为。bit-ecs 在这个基础上，用稀疏集合加密集数组的数据布局，让频繁增删实体和组件这件事本身也做到高性能。
npm install @gongxh/bit-ecs
零依赖，独立使用。
组件必须实现 reset()，因为组件是从对象池里回收复用的，不重置会带着上一个实体的脏数据：
import { Component, _ecsdecorator } from '@gongxh/bit-ecs';
const { ecsclass, ecsprop } = _ecsdecorator;
@ecsclass('Position')
export class PositionComponent extends Component {
@ecsprop({ type: 'float' }) x: number = 0;
@ecsprop({ type: 'float' }) y: number = 0;
reset(): void {
this.x = 0;
this.y = 0;
}
}
系统在 onInit() 里配置要查询哪些实体，update(dt) 里写每帧逻辑：
import { System, _ecsdecorator } from '@gongxh/bit-ecs';
const { ecsystem } = _ecsdecorator;
@ecsystem('Move')
export class MoveSystem extends System {
protected onInit(): void {
this.matcher.allOf(PositionComponent, VelocityComponent);
}
update(dt: number): void {
this.query.iterate2(PositionComponent, VelocityComponent, (entity, pos, vel) => {
pos.x += vel.x * dt;
pos.y += vel.y * dt;
});
}
}
allOf 表示实体必须同时有这两个组件才会被这个系统处理，还有 anyOf（任一）、excludeOf（必须不含）、optionalOf（可选，查询时一并带出但不作为过滤条件）可以组合。
iterate2 这类按数量区分的迭代器（1~4 个组件）是零 GC 的，比通用的 iterate(...types)（支持最多 8 个组件，几乎无 GC）性能更好，热路径（每帧都跑的系统）优先用固定数量版本。
import { World } from '@gongxh/bit-ecs';
const world = new World('battle', 1024); // 最大实体数建议 2 的指数
world.addSystem(new MoveSystem());
world.initialize(); // 必须调用一次
const entity = world.createEmptyEntity();
world.addComponent(entity, PositionComponent);
world.addComponent(entity, VelocityComponent);
// 每帧调用
world.update(dt);
也可以用 SystemGroup 把系统分组，配置 frameInterval 让某些不需要每帧都跑的系统降频，比如 AI 决策系统每 3 帧跑一次：
const aiGroup = world.SystemGroup('AI', 3);
removeEntity、addComponent、removeComponent 都不是调用后立刻改变数据结构，而是延迟到下一帧 update() 前统一处理。这是命令缓冲模式，为的是避免系统正在遍历实体的过程中，数据结构被中途修改导致遍历错乱或者漏处理。
代价是：你在同一帧内调用 removeComponent 之后，马上再 getComponent 去读，读到的还是删除前的数据——它还没真正被移除。这个延迟生效的特性容易让人以为是 bug，实际是设计使然。
稀疏集合加密集数组这套布局，对”频繁加实体、删实体、加组件、删组件”这类场景做了偏向优化，系统遍历性能也不错，代价是内存占用会比纯稠密数组方案高一些——用空间换的是增删的时间。查询器本身会做条件复用，同样的查询条件多次调用不会重复计算，用了掩码做匹配，实体一多的时候也不会线性扫描全部组件类型。
reset() 一定要把所有字段都清干净，漏一个字段在对象池复用时就是隐藏的脏数据 bug，而且这种 bug 通常要跑很多局才会暴露，很难复现。maxEntityCount 建议设成 2 的指数（比如 512、1024），跟内部数据结构的扩容策略更契合。如果你的项目更偏向”节点少、逻辑相对简单”的中小型游戏，不需要 ECS 这么重的架构，可以看看更轻量的 bit-ec。
bit-ecs 那种稀疏集合加密集数组的重型 ECS，是为了应付大批量实体高频增删设计的，但不是每个项目都有这个量级的需求。中小型项目里更常见的诉求其实是”数据和逻辑分开写，组件之间的更新顺序能精确控制，最好还能配个可视化编辑器直接拖属性”，上一套完整 ECS 有点杀鸡用牛刀。
bit-ec 就是为这类场景做的：一个专为 Cocos Creator 优化的轻量实体组件框架，组件区分”数据组件”和”逻辑组件”，更新顺序你说了算，还支持多个世界（比如同时存在的多个战斗场景）互不干扰。
bit-event 是 peer 依赖：
npm install @gongxh/bit-ec @gongxh/bit-event
组件继承 Component，用装饰器注册，属性装饰器支持的类型比较全，包括 Cocos 常用类型（spriteframe、prefab、vec3、color 等），方便配套编辑器直接可视化配置：
import { Component, _ecdecorator } from '@gongxh/bit-ec';
const { ecclass, ecprop } = _ecdecorator;
enum ComponentType {
Health,
Movable,
}
@ecdecorator.ecclass('Health', ComponentType.Health)
class HealthComponent extends Component {
@ecprop({ type: 'int' }) maxHp: number = 100;
@ecprop({ type: 'int' }) curHp: number = 100;
}
class MoveComponent extends Component {
onAdd(): void {
// 组件被添加到实体的那一刻
}
onEnter(): void {
// 实体正式进入场景，这时候可以安全地拿同实体的其他组件
const health = this.getComponent<HealthComponent>(ComponentType.Health);
}
update(dt: number): void {
// 需要先把 needUpdate 设为 true 才会被调用
}
onRemove(): void {
// 组件从实体移除
}
}
onAdd 和 onEnter 分开，是因为组件刚被添加时，同实体上的其他组件可能还没就位，这时候去 getComponent 拿别的组件容易拿到 undefined。等到 onEnter 触发，实体上该有的组件都已经齐了，这时候拿组件互相引用才靠得住。
import { ECManager } from '@gongxh/bit-ec';
ECManager.init(); // 全局只调用一次
// componentUpdateOrderList 决定了各组件类型 update 的执行先后顺序
const world = ECManager.createECWorld('battle-1', battleNode, [
ComponentType.Movable,
ComponentType.Health,
], 300, 10);
const entity = ECManager.createEntity('battle-1', 'Monster_01');
// 每帧
world.update(dt);
多个 createECWorld 可以同时存在，比如 PVP 场景里两个互相独立的小战场，各自的实体、组件互不干扰，一个世界 update 出问题不会影响另一个。
游戏逻辑里经常有依赖顺序的更新：移动组件先算完新位置，碰撞组件再基于新位置判断是否命中，血量组件最后根据命中结果扣血。如果更新顺序是随意的（比如按组件添加顺序或者哈希顺序），同样的代码在不同时候跑出来的行为可能不一致，调试起来很痛苦。
createECWorld 的 componentUpdateOrderList 参数就是让你显式声明这个顺序，框架严格按这个顺序跑每种组件类型的 update，行为可预测。
onAdd() 里调用 getComponent() 去拿同实体的其他组件，大概率拿不到，要拿组件互相引用的逻辑放到 onEnter() 里。update(dt) 默认不会被调用，组件需要显式把 needUpdate 设为 true，纯数据组件不需要每帧更新的话别设，省一点遍历开销。createEntity 第一个参数是世界名，同一个实体配置在不同世界里创建出来的是完全独立的两份实例，互相不共享状态。组件之间跨系统通信、或者要通知 UI 层刷新，配合 bit-event 一起用最顺手，这也是它唯一的 peer 依赖。
模块之间互相调用，最开始图省事直接 import 对方然后调方法，写着写着就变成了一张互相纠缠的依赖网——UI 模块 import 了战斗模块，战斗模块又 import 了 UI 模块，改一个地方不知道会牵动多远。事件系统是解这个问题最常见的办法：谁也不认识谁，只通过事件名义广播，听的人自己决定接不接。
bit-event 是 bit-framework 里最基础的一个模块，零依赖，纯 TypeScript 实现，bit-ec 就是拿它做组件间通信的。
npm install @gongxh/bit-event
import { GlobalEvent } from '@gongxh/bit-event';
// 监听
const id = GlobalEvent.add('mail:new', (mailId: number) => {
console.log('收到新邮件', mailId);
}, this);
// 发送
GlobalEvent.send('mail:new', 1001);
// 只听一次，触发后自动移除，不用手动清理
GlobalEvent.addOnce('game:firstLogin', onFirstLogin);
GlobalEvent.remove(id); // 按具体的监听 ID
GlobalEvent.removeByName('mail:new'); // 这个事件名的所有监听都移除
GlobalEvent.removeByTarget(this); // 这个 target 挂的所有监听都移除
GlobalEvent.removeByNameAndTarget('mail:new', this); // 精确匹配名字+target
实际项目里用得最多的是 removeByTarget——组件销毁的时候，一句话把它注册过的所有监听清空，不用一个个记 ID：
onDestroy(): void {
GlobalEvent.removeByTarget(this);
}
如果某个子系统的事件不想跟全局事件混在一起（比如一个可以整体重置的小游戏内小游戏），创建独立实例，API 跟全局事件完全一样：
import { EventManager } from '@gongxh/bit-event';
class MiniGameContext {
event = new EventManager();
}
// 退出小游戏时一次清空，不影响全局事件系统
miniGameContext.event.clearAll();
事件名建议用常量集中管理，别在业务代码里到处写字符串字面量，拼错一个字母编译期是发现不了的，只有运行时才会发现监听没触发。
// events.ts 集中定义
export const GameEvents = {
MailNew: 'mail:new',
FirstLogin: 'game:firstLogin',
} as const;
另外要小心事件循环：事件 A 的回调里发了事件 B，事件 B 的回调里又发了事件 A，这种链路在代码量小的时候看不出来，模块一多很容易绕出一个死循环，排查起来要一路顺着监听关系摸，比较费时间。
onDestroy 里 removeByTarget(this) 的习惯基本能规避。send 和 sendToTarget 的区别别搞混：send 是广播给所有监听这个名字的人，sendToTarget 只发给指定的那个 target，其他监听同名事件的人收不到。EventManager 实例，不要把这类临时性、局部性的事件也塞进全局事件里，退出的时候不好统一清理。bit-ec 用它做组件间通信，是目前唯一把它当 peer 依赖的模块，但它本身完全独立，任何 TypeScript 项目都能直接拿去用，不限定 Cocos Creator。