企业官网建设流程全解析

Cocos Creator 引擎实验性 API 规范：发布、修订与召回全流程指南

【免费下载链接】cocos-engineCocos simplifies game creation and distribution with Cocos Creator, a free, open-source, cross-platform game engine. Empowering millions of developers to create high-performance, engaging 2D/3D games and instant web entertainment.项目地址: https://gitcode.com/GitHub_Trending/co/cocos-engine

实验性 API 是 Cocos Creator 引擎在功能正式定型前，向开发者提前开放的一类接口。本文以引擎仓库 docs/contribution/experimental.md（中英对照版见 experimental.zh-CN.md）为骨架，系统讲解实验性 API 的发布（Release）、**修订（Revise）与召回（Recall）**三条规范，并结合引擎源码中AnimationClip辅助曲线 API、AnimationController变量 API 等真实案例，说明规范如何落地到实际代码。读完本文，你将掌握：如何为引擎功能打上实验性标记、在什么版本节奏下允许移除实验性 API，以及实验性 API 与废弃（deprecated）机制如何衔接。

一、什么是实验性 API

在引擎功能开发过程中，很多新特性无法一步到位地达到稳定形态——它们可能需要用户的真实反馈来验证设计方向，也可能因迭代需求而在后续版本中大幅调整。此时引擎团队会把这类 API 以**实验性（experimental）**状态先行发布，让开发者可以提前试用，而引擎方保留按需修改的自由。

实验性 API 与正式 API 的关键区别在于契约强度：

二、发布实验性 API：两条硬性要求

当你在开发引擎功能时，若希望在特性正式落地前收集用户反馈，可以按以下两条要求将 API 发布为实验性。

2.1 命名后缀：_experimental（必须）

发布实验性 API 时，必须让 API 名称以_experimental作为后缀。例如一个辅助曲线查询接口应命名为getAuxiliaryCurveValue_experimental，而非getAuxiliaryCurveValue。

这一要求的合理性在于两点：

• 不占用正式名称：实验性 API 不会占据稳定 API 的"正式"命名，即使未来稳定版接口与实验版差异很大，也不会产生命名冲突或迁移困惑；
• 用户零成本识别：开发者无需检查任何警告信息或翻阅文档，仅凭名称即可明确知道该 API 处于实验状态，从而谨慎使用。

从引擎源码可以直观印证这条命名规范。在 cocos/animation/animation-clip.ts 中，动画剪辑的辅助曲线（Auxiliary Curve）相关接口全部遵循_experimental后缀：

public get auxiliaryCurveCount_experimental (): number; public getAuxiliaryCurveNames_experimental (): readonly string[]; public hasAuxiliaryCurve_experimental (name: string): boolean; public addAuxiliaryCurve_experimental (name: string): RealCurve; public getAuxiliaryCurve_experimental (name: string): RealCurve; public renameAuxiliaryCurve_experimental (name: string, newName: string): void; public removeAuxiliaryCurve_experimental (name: string): void;

这些成员均带有@experimental的 JSDoc 注释标记（例如isAdditive_experimental的定义见 cocos/animation/animation-clip.ts），类型定义与文档注释双重标识，确保实验身份清晰可见。

2.2 运行时警告（可选）

在实验性 API 被使用时，可以在运行时附加一条警告级别的提示信息。该提示至多展示一次，避免反复刷屏干扰用户。

引擎提供了warn（见 cocos/core/platform/debug.ts）等调试输出工具，供实现方按需接入。例如 cocos/animation/marionette/animation-controller.ts 中，稳定版getValue方法在检测到用户通过实验接口获取了非基础类型（对象类型）变量时，会输出警告，提示应显式改用getValue_experimental：

public getValue (name: string): PrimitiveValue | undefined { const value = this.getValue_experimental(name); if (typeof value === 'object') { if (DEBUG) { warn(`Obtaining variable "${name}" is not of primitive type, ` + `which is currently supported experimentally and should be explicitly obtained through this.getValue_experimental()`); } return undefined; } return value; }

从这段源码可以看出，警告是可选而非强制的：当实验 API 已经通过命名后缀自曝身份时，是否再附加运行时提示由实现者权衡决定。

三、修订实验性 API：无需向后兼容

在 API 的演进过程中，引擎开发者可以自行决定如何修订实验性 API，不要求保持向后兼容。这是实验性与正式 API 最本质的差异——实验阶段允许设计推倒重来。

但规范同时提出了一条软性要求：应在发布说明（release note）中注明修改内容，如果能在文档中同步说明则更佳。这样即便接口签名被破坏性调整，使用者也能在版本升级时快速定位变化点。

四、召回实验性 API：生命周期与版本节奏

当 API 设计趋于稳定（无论是否存在对应的稳定替代品）后，必须先将实验性 API 转为**废弃（deprecated）**状态，之后才能将其从引擎中彻底删除。这一"先废弃、后删除"的两段式流程，是防止 API 被静默移除、破坏用户工程的关键保障。

规范用"生命期"[a, b]来定义时间窗口：指该 API 在版本a发布（experimental），在版本b稳定（settled）。依据生命期跨越的版本粒度，删除时机分三种情况：

4.1 生命期仅跨越补丁版本 → 下一个次要版本可删

如果实验性 API 的生命期只存在于补丁版本范围内，允许在下一个次要（minor）版本中删除。

例如，若 API 存在于[3.7.0, 3.7.4]（即 3.7.x 系列内完成发布与稳定），可以在3.8.0中删除。

4.2 生命期跨越次要版本 → 等待 Z-Y 个次要版本或下一个主版本

如果 API 的生命期跨越多于一个次要版本，即存在于[X.Y.*, X.Z.*]区间（Y < Z），则只允许在Z - Y个次要版本之后，或在下一个主版本中移除。

例如，若 API 存在于[3.7.1, 3.9.0]，即生命期横跨3.7.x到3.9.x，Z - Y = 9 - 7 = 2，则最早可在3.11.0删除，或在4.0.0主版本中删除。

4.3 生命期跨越主版本 → 仅下一个主版本可删

如果实验性 API 的生命期跨越了多个主版本，只能在下一个主版本中删除。

例如，若 API 存在于[3.0.0, 5.6.7]，则只能在6.0.0中删除，中途任何次版本都不允许移除它。

4.4 规则速查表

这套节奏的本质是给实验性 API 的使用者留出缓冲迁移窗口：API 稳定后，用户仍能在一个或数个版本内继续使用（此时已标记废弃），待迁移完成后引擎再安全移除。

五、与废弃（deprecated）机制的衔接

"先转废弃、再删除"这一要求，与引擎既有的废弃 API 机制直接关联，具体规范见 docs/contribution/deprecated-api.md。该文档详细描述了废弃操作的三个核心函数：

• markAsWarning：在指定对象的属性上嵌入警告（属性需已存在）；
• removeProperty：移除指定对象的属性并嵌入错误信息（属性不应已存在）；
• replaceProperty：重定义被移除的属性，嵌入警告并转发到新属性，必要时适配不兼容的参数。

此外，从 3.6.0 起引擎支持通过deprecateModuleExportedName对导出的模块级名称整体做废弃标记（例如ButtonComponent→Button），项目脚本中一旦import { ButtonComponent } from 'cc'或访问cc.ButtonComponent便会收到警告。

将实验性 API 召回时，正是利用上述机制将其标记为废弃：此时 API 仍可被调用（伴随警告），但已向用户明确传达"即将下线"的信号，与本文第四节的版本节奏共同构成完整的移除流程。

六、引擎中的实验性 API 落地案例

为了让规范具象化，下面从源码中提取三组典型实验性 API 实例。

6.1 AnimationClip 辅助曲线 API

动画剪辑（AnimationClip）的辅助曲线是承载自定义动画数据的重要机制。除名称带_experimental后缀外，cocos/animation/animation-clip.ts 中这些接口还提供了一套完整的增删改查语义：

• auxiliaryCurveCount_experimental：返回辅助曲线数量；
• getAuxiliaryCurveNames_experimental：返回全部辅助曲线名称；
• hasAuxiliaryCurve_experimental(name)：判断指定曲线是否存在；
• addAuxiliaryCurve_experimental(name)：新增曲线，若已存在同名曲线则直接返回现有对象；
• getAuxiliaryCurve_experimental(name)：获取指定曲线（不存在时触发断言）；
• renameAuxiliaryCurve_experimental(name, newName)：重命名曲线；
• removeAuxiliaryCurve_experimental(name)：移除曲线。

这些接口在下层动画图绑定中被实际消费，例如 cocos/animation/marionette/animation-graph-animation-clip-binding.ts 会读取clip.isAdditive_experimental、枚举getAuxiliaryCurveNames_experimental并取值getAuxiliaryCurve_experimental，说明实验性 API 同样可以参与引擎内部运行管线，并非仅面向外部开发者。

6.2 AnimationController 运行时变量与剪辑覆盖 API

动画控制器（AnimationController）的实验性接口展示了"稳定 API 包裹实验 API"的典型模式，见 cocos/animation/marionette/animation-controller.ts：

public setValue (name: string, value: PrimitiveValue): void { return this.setValue_experimental(name, value); } public setValue_experimental (name: string, value: Value): void { const { _graphEval: graphEval } = this; assertIsNonNullable(graphEval); graphEval.setValue(name, value); }

这里setValue是面向用户的稳定入口，内部直接委托给setValue_experimental——实验实现与稳定入口共享同一实现，避免重复维护。此外：

• getValue_experimental/getValue：分别支持完整值类型与仅基础类型（对象类型访问会触发警告并返回undefined）；
• overrideClips_experimental(overrides)：在运行时覆盖动画图中的动画剪辑，且源剪辑必须始终指向原始图中的剪辑对象（首次用[originalClip, newClip1]覆盖后，第二次仍需写[originalClip, newClip2]而非[newClip1, newClip2]），详见 cocos/animation/marionette/animation-controller.ts；
• getAuxiliaryCurveValue_experimental(curveName)：读取指定辅助曲线的当前值，动画图为空或曲线不存在时返回0。

6.3 枚举值中的实验扩展：VEC3 / QUAT 变量类型

实验性标记不仅用于方法，也用于枚举扩展。在 cocos/animation/marionette/variable/basic.ts 中，VariableType新增了VEC3_experimental与QUAT_experimental两种变量类型，并由 vec3-variable.ts 与 quat-variable.ts 提供对应实现。这印证了规范适用的对象范围——属性、方法、枚举成员乃至导出类型，只要处于实验阶段，都应遵循_experimental后缀约定。

七、给引擎贡献者与使用者的实践建议

结合规范正文与仓库实际，可以沉淀出以下可操作的经验：

1. 命名即文档：无论新增方法、属性、枚举还是类型，实验性一律以_experimental结尾，并在 JSDoc 中补充@experimental标记，双保险避免误用；
2. 警告从简：运行时警告应控制在 warn 级别、至多一次，必要时可参考AnimationController.getValue的做法，让稳定入口对"越界使用"做提示性兜底；
3. 版本意识前置：发布实验性 API 时就应预判其生命周期——若只打算存活几个补丁版本，可尽早稳定并转废弃；若长期处于实验态并跨越主版本，则要做好持久维护的准备；
4. 废弃是移除的唯一前置：任何实验性 API 都不能"静默消失"，必须走完"废弃 → 等待版本窗口 → 移除"的完整流程，并同步更新 release note。

对于在游戏项目中使用了引擎实验性 API 的开发者，建议做到两点：一是主动隔离实验代码，由于不保证向后兼容，升级引擎版本时优先回归这些接口；二是关注 release note，实验 API 一旦转废弃，意味着你应尽快迁移到对应的稳定替代实现。

结语

实验性 API 机制是 Cocos Creator 引擎在"快速迭代新特性"与"守护用户代码稳定性"之间取得的平衡：通过_experimental后缀让实验身份透明可见，通过"无需向后兼容"给引擎演进留足空间，再通过"先废弃后删除 + 版本节奏约束"为使用者保留迁移缓冲。理解了这套 docs/contribution/experimental.md 描述的规范，无论是作为引擎贡献者发布新功能，还是作为使用者评估实验接口的风险，都能做到心中有数。

【免费下载链接】cocos-engineCocos simplifies game creation and distribution with Cocos Creator, a free, open-source, cross-platform game engine. Empowering millions of developers to create high-performance, engaging 2D/3D games and instant web entertainment.项目地址: https://gitcode.com/GitHub_Trending/co/cocos-engine