Cocos Creator 2.4.7 正式发布，优化编辑器兼容性与稳定性

工欲善其事，必先利其器。经过长时间的准备和测试，Cocos Creator 2.4.7 终于发布了，感谢所有给予我们宝贵反馈的小伙伴们！在此次更新中，我们对近期发现的一些 2.x 相关问题集中进行了修复，重点提升了编辑器的稳定性、兼容性，建议所有 2.x 用户升级。

在 2.4.5 中，我们为了兼容 Mac M1 尽快升级了编辑器底层的 Electron，导致了开发者的部分插件出现异常，很抱歉给大家造成了不好的体验。针对有关问题，我们在近期进行了大量的专项测试，将兼容性适配代码集中汇总到了 2.4.7，最终为开发者抹平了 Electron 版本的差异，并且确保不会引入新的相关问题。

在之后的版本中，不论是 2.x 还是 3.x，我们都将秉持兼容第一的原则，并且持续验证 Cocos Store 中的插件兼容性，尽可能在基础设施变化时不影响项目、插件的运行，减少适配成本，提升升级体验。

根据今年 2 月 7 日 3.0 版本正式发布时的计划，2.4 作为 LTS 版本将在今年继续提供缺陷修复。同时明年全年，我们还将持续关注 2.4 的关键问题和重大的平台适配问题，不定期更新版本，支撑线上项目的安全运营，请大家放心。

再次集中解答一下关于 3.x 的升级问题：

• 新项目不再建议基于 2.4，请统一使用 3.x 版本进行开发，我们会一如既往地优化 3.x 的开发体验，关注轻量级游戏的包体和效率，支撑好 2D、3D 等不同品类的游戏开发。

• 当前 2.x 项目如果已到开发中期，或者即将上线，不必升级 3.x。

• 当前 2.x 项目如果还在开发前期，可以评估是否需要升级 3.x。如果确认一定要升级，可以使用 Creator 提供的 2.x 资源导入工具。此工具将支持旧项目资源完美导入，以及代码的辅助导入。代码辅助导入会把 js 转换成 ts，添加组件类型声明、属性声明及函数声明，组件在场景中的引用都会得到保留，并且函数内部的代码会以注释的形式导入进来，可以减轻开发者的升级难度。详细的升级说明请参考[升级指南]。如果开发者们在升级中遇到困难，欢迎向我们反馈，我们会尽力协助。

Stack Changes 

• 升级编辑器的 Electron 版本到 13.1.4。解决了 Windows 上部分用户频繁出现的 WebGL 崩溃问题，还支持了 M1（Apple Silicon）的原生 ARM 指令集，建议所有 M1 用户升级以获得更好的性能。详见升级说明。

• 升级 Android 工程 Gradle 版本到 4.2.2 版本，详见升级说明。

Editor 

• 修复 Prefab 打开时点击保存，可能覆盖场景数据的问题

• 修复编辑器下刷新脚本时，若无场景切换操作则内存会持续增长的问题，感谢 isilent

• 修复重复构建部分文件 MD5 可能发生变化的问题

• 修复 2.4.5 出现的部分第三方插件 ui-section 内 header 使用 class 注册的语法不兼容的问题

• 调整构建时的资源压缩操作到拷贝构建模板和 `beforeFinish` 事件之后

• 修复构建后修改脚本并绑定节点后再次构建，运行时绑定内容可能为空的问题

• 修复资源管理器，搜索后键盘上下选择节点错误的问题

• 修复在资源管理器全选 audio-clip、sprite-frame、texture 后拖动面板会报 resize 错误的问题

• 修复聚焦场景后，选中节点无法删除的问题

• 修复预制体自动同步弹窗状态无法保存的问题

• 修复节点上 Color 等属性改动后，使用撤销和重置节点属性无效的问题

• 修复资源路径或项目路径中带有括号时，打开编辑器出错的问题

• 修复点击 Markdown 中的超链接失效的问题

• 修复 Prefab 未修改保存后数据发生变化的问题

Engine 

• 修复预加载没有下载自动图集的图片的问题

• 修复修改父节点后，节点的透明度级联计算错误的问题 [#9322]

• 修复 Scroll View 同时到达水平和竖直边界时，没有正确触发事件的问题，感谢 zty8023ys [#9445]

• 修复 Mask 组件在运行时调整节点大小无效的问题 [#9444]

• 修复 Graphics Bezier 曲线的重绘问题，感谢 caogtaa [#9194]

• 修复 EditBox 在 PhoneNumber 模式下，鼠标滚轮导致数字为负数的情况，感谢 wanghaha1991 [#9138]

升级说明 

Cocos Creator 对项目的升级操作是不可逆的，请在升级前提交或备份旧版项目。绝大多数项目通常都能自动升级，但因为项目难免存在特殊性，开发者应该根据项目自身需求，提前对新版本引擎进行试用和评估。此外，出于稳定性考虑，建议即将上线或已上线的项目谨慎升级。以下是升级说明，如果开发者们在升级中遇到困难，欢迎向我们反馈，我们会尽力协助。

从 < 2.4.7 版本升级

• 从 2.4.7 开始，安卓工程的 Gradle Plugin 版本升级到了 4.2.2。此次升级调整了 Android Instant 工程的目录结构，对普通 Android 工程没有影响。我们移除了 js-template-link/frameworks/proj.android-studio/game 与 js-template-default/frameworks/proj.android-studio/game 目录。game 目录中的内容与 instantapp 目录已合并进 instantapp 目录，如果有对应的模板定制的内容，需要迁移至 instantapp 目录中。

• 从 2.4.7 开始，编辑器底层 Electron 升级到了 13.1.4，我们为 Electron 自身的大部分接口变动进行了兼容处理，例如 BrowserWindow 启动默认值、shell.openItem、shell.moveItemToTrash 以及部分 Node.js 环境内的数据。但基于 Electron 官方的安全性建议，如果插件使用到了 <webview> ，请通过 <webview nodeIntegration></webview> 显式开启 Node.js 支持。如开发者还遇到 2.4.7 引入的其他插件兼容性问题也欢迎向我们反馈。

从 < 2.4.0 版本升级

• cc.loader 已经不建议使用，请使用最新的 cc.assetManager 来代替，请参考[资源管理模块升级指南]

• 子包功能已升级为 Asset Bundle，请参考[资源分包升级指南]

• 调整了项目构建后的目录结构，调整了 BuildResults 的 API，如果你使用了编辑器插件获取编辑器构建结果，请参考[定制项目构建流程升级指南]

• 从 1.10 开始废弃的 cc.RawAsset 已被正式移除，请使用 cc.Asset 代替。由于 2.4 不再兼容原有 1.x 项目中对 RawAsset 类型的历史遗留用法，建议所有要升级到 2.4 的项目特别是从 1.9 版本一路升级上来的项目，先在任意的 1.10 ~ 2.3 版本中对编辑器编译代码时输出的所有警告或报错都正确处理完毕，再升级到 2.4。

• cc.Color.fromHex 已被废弃，请使用 cc.Color.fromHEX 接口。

从 < 2.3.3 版本升级

• Effect 中的 CCTexture2D，CCTexture2DRGB 方法已被废弃，请改用 CCTexture，CCTextureRGB

• Vec3.FRONT 已被废弃，请改用 Vec3.FORWARD 

从 < 2.3.0 版本升级

从 2.3.0 开始，定制安卓原生工程时，需注意 Android 与 Android Instant 使用了同一个构建模板。

• 如果是 Android 平台单独使用的代码请放入 app/src 目录,  单独使用的第三方库请放入 app/libs 目录。
• 如果是 Android Instant 单独使用的代码和第三方库请分别放入 game/src, game/libs 目录。
• 如果是 Android 和 Android Instant 共用的代码和第三方库，请分别放入 proj.android-studio 根目录底下的  src 目录和 libs 目录。
• proj.android-studio 根目录底下 jni/CocosAndroid.mk , jni/ CocosApplication.mk，主要用于配置引擎相关的配置，开发者的配置，建议 Android 放到 app/jni/Android.mk 和 app/jni/Application.mk中，Android Instant 请放入 game/jni/Android.mk 和 game/jni/Application.mk 中。

此外，在 Cocos Creator 编译 Android 时会默认执行 assembleRelease/Debug，编译 Android Instant 时会执行 instant:assembleRelease/Debug。

如自定义了音频前后台切换时的暂停逻辑，升级到 2.3.0 后请移除。

目前 Creator 游戏在所有平台上前后台互相切换时，都会在内部自动暂停和恢复音频。如果开发者之前有对这一块进行过定制，监听并执行了 cc.audioEngine.pause()/resume() 之类的音频操作，可能会和引擎默认行为冲突。如果有遇到相关的音频问题，只需移除相应的定制代码即可。

从 < 2.0 - 2.3.0 版本升级

从 2.3.0 开始，Canvas 组件不再负责将 Canvas 节点尺寸设为屏幕大小，此行为将结合 Widget 组件实现。为保证兼容性，2.0 项目升级后，Canvas 所在节点会自动添加 Widget 组件。（从 1.x 项目升级无此问题）

从 < 2.2.0 版本升级

从 2.2.0 开始，我们强化了内存管理机制，现在要求用户通过代码动态创建且独立于场景节点树的 cc.Node 必须通过 destroy() 释放，否则引擎无法知道何时回收这类节点的内存，会导致内存泄露。

• 如原先手动从场景中移除的节点，在不需要用到的时候也需要统一 destroy()：

// 假设 testNode 是场景中的某个节点，若之前被手动移出场景了，如
testNode.parent = null;
// 或者
testNode.removeFromParent(true);
// 或者
parentNode.removeChild(testNode);
// 若往后 testNode 还会再次用到，则无需手动 destroy 该节点
// 否则应该手动调用
testNode.destroy();

• 如原先通过 cc.removeSelf 这个 action 销毁节点，请改为使用 cc.destroySelf

• 如原先通过 cc.NodePool 管理节点，则不受影响

从 2.2.0 开始，我们不再建议你使用节点的 Skew 功能。

Skew 通常用作在 2D 引擎中模拟 3D 效果，随着 Cocos Creator 对 3D 节点的深入支持，Skew 效果已经完全可以由 3D 节点来实现。为了统一使用体验，进一步优化引擎底层实现，我们在 3.0 中废弃了 Skew 属性。

从 < 2.0 版本升级

打开 1.x 项目的话，场景等所有资源将会自动升级，代码中的废弃接口从 2.3.3 开始将会在保持兼容的基础上同步输出报错。升级方式可参考「1.10 资源升级指南」和「2.0 升级文档」进行调整。

点击文末【阅读原文】前往官网下载最新版本，欢迎大家使用与体验，再次感谢各位开发者的支持！

参考链接 

[升级指南]

https://docs.cocos.com/creator/3.0/manual/zh/release-notes/upgrade-guide-v3.0.html

[#9322]

https://github.com/cocos-creator/engine/pull/9322

[#9445]

https://github.com/cocos-creator/engine/pull/9445

[#9444]

https://github.com/cocos-creator/engine/pull/9444

[#9194]

https://github.com/cocos-creator/engine/pull/9194

[#9138]

https://github.com/cocos-creator/engine/pull/9138

[资源管理模块升级指南]

https://docs.cocos.com/creator/manual/zh/release-notes/asset-manager-upgrade-guide.html

[资源分包升级指南]

https://docs.cocos.com/creator/manual/zh/release-notes/subpackage-upgrade-guide.html

[定制项目构建流程升级指南]

https://docs.cocos.com/creator/manual/zh/release-notes/build-extend-upgrade-guide.html

[1.10 资源升级指南]

https://docs.cocos.com/creator/manual/zh/release-notes/raw-asset-migration.html

[2.0 升级指南]

https://docs.cocos.com/creator/manual/zh/release-notes/upgrade-guide-v2.0.html

往期精彩