为什么版本演进是理解 Flecs 的第一块基石

上一篇我们聊了 ECS 思潮从哪来、Sander Mertens 为什么自己动手写一个框架。那篇讲的是想法，这篇讲想法怎么被现实揍了七年后长成今天这个样子。

说句实话，选框架最常犯的错，是看今天的 README 而不是看它的伤疤。README 告诉你它能做什么，伤疤告诉你它以后会不会再伤你一次。一个框架第一次大重构的地方，往往就是它真正的设计核心；一个框架反复改回去的地方，往往就是它至今没想清楚的地方。

所以这篇我打算干一件不那么性感的事：把 Flecs 从 1.x 到 4.x 的公开版本史，翻译成一份「能不能押注它」的判断依据。你不需要记住每个版本加了哪个接口，你需要记住的是——每个版本在解决什么矛盾，代价是谁付的，以及这些代价对你这种规模的团队意味着什么。

先给个结论垫底：Flecs 的版本史不是一条平滑上升线，而是四次「推翻自己」的记录。1.x 证明想法能跑，2.x 装上时间轴，3.x 找到了别人没有的东西，4.x 才开始像一个平台。你现在选的不是「最新版」，你选的是这四个阶段的终点，同时也在赌第五个阶段。

第一层：1.x —— 一个人的实验田，卖的是「能跑」

Flecs 起于一个很朴素的念头：那套在 3A 项目里被验证过的数据导向架构，能不能在纯 C 里、用一个头文件跑起来。所以 1.x 时代的它长得很朴素——实体就是一个整数编号，组件就是一堆数据，系统就是一段遍历，全部接口平铺在同一个 C 前缀下面，不绕弯子。

注意，这个阶段的 Flecs 里没有帧的概念，没有阶段划分，没有查询缓存，没有关系，也没有序列化。你想控制执行顺序？在主循环里按你自己的顺序调用。听着挺原始，但它精准命中了当时一批人的需求：我只想要一个干净的实体容器，别给我塞一整套世界观。

它的假想敌是 EnTT。两家几乎同时在做同一件事，但路线完全相反：EnTT 走稀疏集，一个组件一个池，加组件删组件几乎瞬时完成，实现极简，单头文件几百 KB 就能塞进任何工程；Flecs 走的是另一种路子，把组件组合相同的实体放在连续内存里，遍历更快，但增删组件时会「搬家」。这个选择在 1.x 时期是纯粹的取舍——更重、更难写、但热循环里跑得更快。

这段历史对今天还有什么用？有，而且很实在。1.x 给 Flecs 留下了两个一直没变的性格：第一是能不加依赖就不加，纯 C 实现，任何引擎、任何平台都能挂上去；第二是接口风格偏「平铺」，它不会替你藏东西，代价是你得自己组织代码。你后面在 4.x 文档里感受到的那种「东西很多、但都在明面上」的味道，源头就是这一层。

另外说个现象。1.x 时代的示例代码至今还散落在各种博客和搬运站上，看起来跟今天的 Flecs 有点像，但一抄就编译不过。这不是文档烂，这是跨度太大了——你看到的其实是两个不同物种。

第二层：2.x —— 把「帧」写进框架，第一次推倒重来

如果说 1.x 是证明想法能跑，那 2.x 就是 Flecs 第一次承认：我要管的不是一个实体表，是一整个游戏的运行时。

这个版本的核心动作是把流水线做进内核。开发者可以声明「这段逻辑跑在物理之后、表现之前」，框架自己排顺序，自己判断哪些能并行。往上一层的体验是——你第一次能把一帧画成一条时间线，而不是一坨互相调用的函数。

为什么说这是分水岭？因为它定义了 Flecs 之后的整个世界观。从 2.x 开始，「系统」不再只是一个遍历回调，而是一个有位置、有依赖、有执行约束的调度单元。后来 4.x 的多线程、阶段划分、观察者触发时机，全都长在这个骨架上。

代价也在这里。系统层几乎是重写的，1.x 用户的代码基本等于全废。我印象最深的是那个阶段的社区气氛——有一批人不是抱怨功能不够，而是抱怨「我刚写顺手的东西又变了」。说句公道话，这种抱怨特别真实，因为对一个正在赶进度的小团队来说，框架升级不是学习成本，是排期风险。「Flecs 变化太快」这个名声，就是在那两年被钉上去的，到今天还在传。

但你要理解作者的处境：一个人维护的框架，没有大厂那种「旧接口养三年」的余裕。每多留一个旧接口，就多一份维护债务，多一批不知道怎么选的用户。所以 Flecs 的选择一直是：与其加适配层，不如直接砍。这个取向好不好，我们放到后面的争议部分聊。

第三层：3.x —— 关系革命，Flecs 开始有别人没有的东西

3.x 是 Flecs 历史上最重要的一次跃迁，也是它真正跟其他框架拉开距离的地方。核心就一件事：关系从「可以用的特性」升级成「一等公民」。

什么叫一等公民？就是实体和实体之间的那条连线，本身也是一个可以被查询、被附加数据、被贴标签描述的东西。父子是关系，模板和实例是关系，玩家和背包是关系，技能和施加者也是关系。更关键的是，关系可以带「性格」——比如可传递：A 挂在 B 上面、B 挂在 C 上面，那么查询「C 下面所有东西」时能自动刨出 A；比如独占：一个玩家身上只允许存在一个背包。

落到玩家能感知的层面，变化是这样的。以前你写「背包里有什么」，大概率是一个组件里塞个数组，加东西删东西的时候手动同步一堆状态。现在你挂一条边，查询顺着边走。以前你写「身上的增益效果」，可能是一张表加一个计时器管理器。现在增益本身就是实体，挂在角色身上，到期了删掉这条边，世界自己就干净了。

这不是语法糖，这是数据模型层面的胜利。判断标准很简单：当你发现自己的代码里有一半在维护「谁指向谁」的一致性，而不是在写游戏逻辑，那关系就是解药。

解药也有毒性。每条边都会影响实体属于哪张内存表，也就是说，父子关系一变，实体就搬家。子弹打出去又销毁、UI 列表每秒重排、掉落物频繁换归属——这些场景如果全用关系表达，内存表会被切得很碎，遍历性能反而掉下来。这个坑是 3.x 之后才被大量讨论的，前面讲内存模型那篇里有更细的账，这里先记住一句话：关系好用，但不是免费的，它把「一致性维护」的成本从你的代码里换成了运行时的内存布局成本。

案例说一个。Passtech Games 的《Ravenswatch》是 Flecs 公开的项目案例之一，这是一款体量不大的动作 roguelike，角色多、技能多、状态多、词条多。这类游戏的数据组合是爆炸式的：一个角色身上可能同时挂着中毒、减速、护盾、武器附魔、临时增益，还可能被挂上某个首领的仇恨标记。用继承树写这种东西，树会写到你自己都不认识；用「每样都开一个组件」，组合数会失控。关系型表达让「谁挂在谁身上」变成了数据而不是代码分支，一个查询就能把「所有挂在玩家身上的负面状态」捞出来统一处理。选拔层面的意图很清楚：内容量靠组合，组合靠数据，数据靠关系。我不敢替他们做技术复盘，但时间线和用法是对得上的。

顺手做个跨类对比，别以为这是 Flecs 独有的烦恼。Unity 的 DOTS Entities 从 2018 年的早期版本到 2023 年才算正式 1.0，五年里换了两代写法，连编辑器里的工作流都反复推翻，社区骂声一点不比 Flecs 小。可它背后是 Unity 的体量和人力。一个单人项目干类似量级的事，破坏性升级就是必然。这条对比想说明的不是谁更烂，而是：ECS 这个领域本身还在变，任何声称「架构已经稳定」的框架，多半只是没在改。

第四层：4.x —— 平台化：查询语言、稀疏组件、可裁剪的模块

4.x 是 Flecs 第一次可以被称为「平台」的版本，也是它第一次在 API 稳定性上值得你下注的版本。这句话我说得比较重，下面拆开讲。

第一件大事是查询的表达方式变了。以前拼一个查询，是一串接口调用叠起来；4.x 引入了声明式的查询写法，把「我要什么」直接写成接近自然语言的表达式。好处有两个：一是可读性上来了，策划或者新人看一眼大概知道在捞什么；二是调试友好，性能分析工具里能直接看到这条查询在干什么。对一个中大型项目来说，这直接影响的是「三个月后你还记不记得这段代码在干嘛」。

第二件大事是观察者体系被重做。旧版本里你想知道「某个组件刚被加上」，往往得每帧去比对；4.x 的观察者让你直接挂一个反应，实体变化的那一刻触发。这对做技能触发、成就系统、UI 绑定的团队是决定性的——它把轮询的活儿变成了事件。当然高频触发也是新的性能陷阱，这个我们后面单独开一篇讲。

第三件大事，也是我觉得对独立团队最实惠的：稀疏组件。有些组件数据量很大但只挂在极少数实体上，比如一把枪的完整参数、一个存档点的额外信息。传统做法是只要挂这个组件，实体就会被划到另一张表里去，等于用一个稀有组件污染了大量实体的内存布局。稀疏组件让你把这些稀有数据放到旁边，不参与表划分，主体的遍历速度不受影响。这个特性属于那种「不看文档不知道，用了之后省一大截」的类型。

第四件大事是工程层面的：C 和 C++ 的接口分家了，序列化、脚本、统计这些能力被拆成可选模块，你可以只编你需要的部分。这个变化对独立开发者是实打实的包体和编译时间收益，尤其你要发布到主机或者浏览器的时候。同时它也带来一个副作用——网上那些「一行命令全开」的老教程，在新版本上往往跑不起来。

代价当然也在这儿。4.x 的变动面是历史上最大的一次，很多 3.x 甚至 2.x 的教程、示例、第三方文章全部失效。你要是 2024 年才开始用 Flecs，恭喜你避开了所有坑，但你也享受不到「网上到处是能抄的代码」这种便利。这就是单人维护框架的另一面。

参数化设计工具：版本跟进决策表与健康度标尺

讲完历史，给你两张能直接抄进团队文档的表。第一张是「我该跟到什么程度」，第二张是「我怎么判断这个框架还值不值得跟」。

第二张表更关键，我管它叫框架健康度标尺。选框架的时候别只看性能测试，那玩意儿换个场景就翻盘，看这个更靠谱。

再给一个我自己用的土办法：如果一个小版本的新增内容里，超过三分之一是「改名 / 调整参数顺序 / 挪位置」这种动静，那就是 API 还没定型的信号。Flecs 在 4.x 之后这一类动作明显变少了，这是我判断它进入稳定期的主要依据，比任何公告都实在。

最后一个可调参数，是关于你在自己项目里留多少「缓冲层」。建议是：把所有直接触碰框架的地方收敛到一层薄封装里——实体创建、组件注册、查询定义这三件事统一走你自己的入口。这层封装会增加大概 5% 到 10% 的样板代码，但能把主版本升级的改动面压到原来的三分之一。这笔账在小团队里几乎是必赚的。

初级用户速览：你只需要记住三句话

第一句：今天入场，直接用最新稳定版，别抄老教程。你在网上搜到的 Flecs 代码，一半属于上一个时代。判断方法很简单——如果示例里没有声明式的查询写法，基本就是旧版本，看到就关掉。宁可看官方仓库自带的示例，也别信搬运博客。

第二句：先把两个关系学会，其他都先放着。一个是「父子」，一个是「模板」。这两个能覆盖你八成场景：场景图、UI 层级、装备和角色、技能和施法者。至于你自己定义新关系、给关系加特性，等你真的被「一致性维护」折磨过一轮再去学，那时候你才看得懂它好在哪。

第三句：主版本不兼容是常态，升级前先打标签。这不是 Flecs 的毛病，是整个数据导向领域的共性。养成两个习惯就够了：每次升级前在仓库打个标注，以及写一个「打开游戏、跑三十秒、对比结果」的回归脚本。这两件事花你半小时，能省你两天。

初学阶段最该警惕的不是难，是「假熟悉」。你在别的框架里攒的经验，有相当一部分在这儿不成立。比如你会本能地想给实体加个类型标签做区分——在这套体系里，正确的做法往往是加一个空组件。这类思维切换前面那篇讲过了，这里只提醒一句：别用旧地图找新大陆。

进阶用户深入：把升级变成一件可管理的事

如果你已经在用，或者正准备把它引进一个真实项目，下面这套流程是我自己踩过坑之后总结的，能省你不少头发。

读发布说明的方式要改。大部分发布说明长得像流水账，你只需要找出「破坏性变更」那一节，其他全部跳过。新增功能你迟早会在需要的时候找到，被改掉的东西你必须提前知道。我一般会在升级前把这一节抄进项目文档，写清楚每条影响了我们哪几个文件。

建那层薄封装，再说一次。具体封什么：实体的创建和销毁、组件的注册和查询、系统的注册和阶段归属。这三样封住了，你的业务代码就跟框架解耦了。升级的时候你只面对一个文件，而不是面对一百个文件里的散弹。

用快照对比来验证行为。这套框架可以把整个世界状态序列化出去，这是个被严重低估的能力。升级前后跑同一段脚本化的场景，导出两次世界状态做比对，比肉眼验证靠谱一百倍。我把这个法子叫「录播回归」——录制一段游戏行为，重放，对比。

绝对不要一次跨两个主版本。听起来是废话，但我真见过有人从很老的版本直接跳最新，然后花两周对着编译错误怀疑人生。中间那个版本的作用是给你一个过渡参照：先升到它，让代码能跑，再升到最新，你至少知道问题出在哪一段。

关心一下模块边界。新版本里很多能力是可选模块，序列化、脚本、统计都是。这意味着你可以按需裁剪，也意味着你不该把这些能力的细节直接写进业务逻辑。哪天你想换个序列化方案，边界清楚的项目改一处，边界糊的项目改一个月。

最后一件事，关于心理预期。你得接受一个事实：你用的框架是一个人在维护的，它的演进速度会快过你的项目节奏。这不是坏事——意味着它还在成长；但你必须自己筑堤。筑堤的方式就是上面那四条：薄封装、快照回归、单步升级、关注边界。

争议区：四个流传很广的误会，和一个真实的风险

还有一种坑不属于框架，属于人：把旧版本的经验当成新版本的事实。这话我也对自己说过——我曾经笃定某个特性「肯定没有」，结果人家两个版本前就加了。承认自己跟不上，然后老老实实翻发布记录，比在群里问一句「有没有人知道」快得多。

FAQ

问：现在这个版本之后，还会不会有大的破坏性升级？

主版本之间一定会，这是数据导向领域的常态，任何承诺「以后都不改了」的框架你反而要警惕。但从 4.x 的表现看，接口命名层面的折腾明显收敛了，更多是在加能力和优化性能。我的判断是：接下来两年你最大的风险不是「接口又改名」，而是「新特性你想用但迁移成本高」。

问：我手上有很老的版本写的代码，能平滑迁到最新吗？

平滑不了，别抱幻想。但有个好消息：你能保住的是思维层面的资产——组件怎么切分、系统怎么排阶段、关系怎么建模，这些都不会失效。要重写的只是表层写法。我的建议是别在原工程上硬改，新建一个工程边搬边重构，你会发现搬的过程中顺手把很多历史包袱扔了。

问：为什么这个框架的版本号跳得这么快？是不是不稳定？

早期确实跳得快，因为作者在快速试错，而且没有商业压力逼他保守。但版本号跳得快不等于质量差，得看跳的原因：是因为发现了更好的架构而重构，还是因为一直在补漏。从一个外部使用者的视角看，前几次大改每次之后能力都明显上了一个台阶，属于前一种。

问：我用的是别的语言的绑定，版本演进对我有什么影响？

影响挺直接：绑定层通常滞后于核心，核心一改，绑定要等一段时间才跟上。所以如果你是脚本语言用户，跟进策略要比 C 用户更保守，锁版本锁得更死。另外注意一点：脚本层的接口设计往往是二次加工过的，它可能不暴露核心的全部能力，你得先确认你要的功能在绑定里存在，再决定用不用。

问：怎么快速判断一个版本值不值得升？

三个问题：它修的问题我遇到了吗？它加的能力我现在就需要吗？它打破的东西我碰得到吗？前两个是收益，第三个是成本。三个都是否，那就是纯风险，别升。这跟谈恋爱一个道理——不是所有更好的都适合现在的你。