介绍
淘宝小游戏技术特性与迁移指引
引言
为了帮助开发者了解淘宝小游戏与其他平台在技术规范与接入过程中的差异，以及实践中常见的问题，我们整理了本说明文档。内容将聚焦开发者在接入、开发过程中最需要关注的点，包括平台能力、技术规范、商业模式与审核要求。希望通过本说明，开发者能够快速明确两端的差异，从而更顺利地进行版本适配与上架。
1. 技术能力差异
1.1 基础框架差异说明
鸿蒙系统
淘宝小游戏2025年12月底支持纯血鸿蒙系统，鸿蒙端仅支持高性能模式。
全局变量
类似于浏览器的 Window 和 NodeJS 的 global，淘宝小游戏提供了一个全局对象 globalThis。通过 globalThis 可以在多个文件中传递变量。
// 文件a.js globalThis.foo = 1;
// 文件b.js console.log(globalThis.foo); // 输出 "1"
但需要注意的是，全局变量需要显式的访问，不可以缺省 globalThis。
console.log(globalThis.foo); // 可访问 console.log(foo); // 不可访问
包体限制
① 主包不超过4M；
② 单个分包不超过5M；
③ 主包+分包总计不超过20M；
详细内容请见：分包加载-小游戏接入指南。游戏如有特殊的超限诉求，可联系平台方申请扩容。
渲染方案差异
新接入游戏要求使用高性能模式，以保障游戏的流畅度和体验。高性能模式最低可用的手淘版本为10.46.0，低于此版本会自动降级普通模式。
此版本线上已经高比例覆盖，各项能力与普通模式一致，开发阶段无特殊情况可忽略普通模式的适配。
iOS内存限制：
iOS系统的内存限制严格，低端机(6s/7/8 等)2G RAM 机型的内存限制为 1G，其他机型的安全内存建议控制在1.1G内，超过该限制可能会导致出现游戏异常退出、白屏后刷新等问题，进而造成用户投诉。
由于利用了 iOS 系统的 WKWebView 能力，小游戏的进程名一般为 WebContent，在使用性能测试工具时，请找到对应的 WebContent 进程进行测试。 一般系统可能存在多个 WebContent 进程，因此需要找到当前小游戏对应的 WebContent 进程再进行测试。
注意：淘宝小游戏目前不支持高性能+模式
1.2 游戏引擎适配
淘宝小游戏目前支持Cocos与Laya引擎，其余引擎暂无官方适配支持。
Cocos引擎说明：
支持版本：
- 3.x在3.7.3及后续版本。
- 2.x在2.4.12及后续版本。
已知问题：
- 目前不支持自定义字体。
- astc资源：Cocos Creator 引擎需要3.8.5 和 2.4.15 以上才支持淘宝小游戏的astc资源导出。3.7.3版本可联系平台获取定制版编辑器，其余不支持的版本需要手动处理。
Laya引擎说明：
支持版本：
- 3.x在3.1.1及后续版本
- 2.x在2.13.4及后续版本
- 1.x在1.8.17及后续版本
1.3 API 能力差异说明
磁盘存储：
淘宝小游戏默认支持最大磁盘存储是200MB（temp+usr目录合计）。有扩容可联系平台运营申请扩展上限。
但为保护用户设备的可用空间，在收到手淘整体可用空间告警时，系统会对用户游戏缓存以游戏粒度进行清理，请开发者合理使用。
另外需要注意的是，淘宝小游戏对文件存储缓存的机制与其他平台有一些差异，具体参考缓存机制说明。
缓存机制说明：
游戏使用my.download下载所有资源默认会直接缓存复用，用户访问后缓存率会迅速提升。在此前提下，游戏引擎的LRU缓存机制在手淘会被平台默认关闭，以减少文件IO和不必要的冗余。
缓存文件会被放进file://temp中，大部分情况下此目录不会被清理，除非遇到系统资源紧张等情况。因此类似其他平台中手动的从 file://temp拷贝至 file://usr 的操作是没有必要的。
文件处理：
- 因缓存机制，Download接口有概率会下载到老数据，如有刷新诉求，可以添加参数强制下载最新数据。设置my.download接口的forceReuse参数值为false，可跳过淘宝平台缓存下载最新文件。
- 如遇OUT_OF_SPACE的错误就是文件夹超过存储限制了，此时可调用removeSavedFile接口清理文件。
触摸事件：
my.onTouch收到的 TouchEvent.touches 属性是一个 TouchList 对象，不支持forEach，需要用for循环遍历。
音频：
多音频同时播放，会出现延迟播放丢音频的情况。此问题平台侧正在修复中，建议控制同时播放的的音频不超过5个。
WebSocket：
网络请求&Websocket不支持二进制传输，需要开发者转成base64字符串进行传输。
1.4 三方库引入说明：
使用部分第三方库会存在全局变量问题，一些已知三方库的处理方案如下
bignumber.js
现象：报错TypeError：i is not constructor
添加下图红圈判断逻辑
第三方FGUI插件
现象：cocos项目在导入fgui时，报错TypeError：Object prototype may only be an Object or null
第三方fgui插件使用window,应该改为globalThis 如图：
修改前：
修改后：
protobuf.js
在cocos项目根目录中npm install protobufjs
npm install 后参考截图的引用：
crypto-js
现象1：Cocos 3.x项目引入第三方库crypto-js，IDE编译报错Module not found
报错如图：
目前的临时方案如下：使用第三方库crypto-es
现象2：Cocos 2.x项目如何引入第三方库crypto-js
- 找到crypto-js需要用的js以及相关依赖脚本。
- 导入到项目中作为插件。
- 修改crypto-js中代码。如图：
- 脚本的调用。如图：
1.5 后端服务接入
外部服务对接需要经过平台网关转发，详情参考：外部云服务对接
2. 开发与接入流程
- 开发调试工具
开发调试：
平台提供了面向开发者的IDE（淘宝开发者工具），包含了应用管理、开发调试与包上传等主要功能。
开发过程推荐使用真机调试功能，在手淘中进行功能的预览与调试。IDE中的模拟器会有一些功能无法支持，导致与真机中的实际表现不一致。
IDE预览功能的使用场景：
预览功能打包较快，适合常规的功能预览与调试。手淘端的预览界面中集成了VConsole工具，可支持非复杂场景的调试需求。
IDE真机调试的使用场景：
注：仅支持安卓设备
首次使用需要下载调试内核，请耐心等待下载完成并手动重启手淘。
真机调试面板功能更加丰富，推荐用于问题排查、性能调试等重度的适用场景。
- 上线前功能验证、审核要求与常见不通过原因
- 主链路功能异常，如启动白屏、卡loading、异常卡顿等；
- 埋点缺失或不准确，包括启动性能上报、游戏关键行为上报等；
- 功能性问题，如非必要的授权唤起、分享问题、快捷方式添加异常等；
3. 迁移与适配建议
【必选】启动性能上报
参考文档：https://miniapp.open.taobao.com/doc.htm?docId=121853&docType=1&tag=game-dev
4. FAQ
- Android桌面快捷方式进入游戏 ，无法通过$global.my来获取my对象，需要使用$globalThis.my来获取。
- 淘宝小游戏有可能是因为帧数太高导致发热严重，先尝试开启手机省电模式以降低游戏帧率。若此操作能解决发热问题，可联系运营进一步降帧处理。
