小游戏技术指南｜高频问题超全解答
2022
summer
小游戏开发者
技术指南
抖音开放平台
技术高频问题超全解答
小胖局不仅一口气汇总了
《2022夏天，小游戏开发者最关注的技术问题》
还拉着程序猿小哥哥们一起给出了 🛎 保姆级解答
😝 快来看看！
还有没有你不知道的吧？
如果还有 🤔
（那一定是我的问题）
进入文末技术群速速提问
... 我真的会秒回 ...
一、关于
开发者工具
Q：
开发者工具打开后白屏，无法启动
A：
请至开发者工具更新及下载（抖音开放平台-普通小游戏开发-开发者工具-开发辅助-开发者工具更新及下载-开发者工具版本列表）页面，下载1.1.0-game及之后的最新版本。
Q：
上传或者预览失败，报错 Unexpected Token/ 查询编译进度失败
A：
一般为开发者工具网络问题，请尝试关闭机器代理、VPN、切换网络环境（切换 WiFi/热点）后重新上传预览。
Q：
上传/预览失败，报错 bad session
A：
开发者工具登录态过期，注销账号重新登录后可以恢复正常。
Q：
载入小游戏工程后，控制台报错找不到 electron-log.js 文件
A：
开发者工具内部文件报错，实际不影响小游戏运行，且载入后第一次运行出现，刷新后本次工程就不会再出现了，这个可以忽略。后续会移除无关 log，减少对开发者的影响。
Q：
开发者工具上传小游戏包提示包体积问题
A：
小游戏包有包体大小限制。1.1.0-game 版本过后，该规则进一步细化明确，包括针对分包小游戏 / 普通小游戏的不同限制逻辑、包体积计算方式。具体请关注官方文档（抖音开放平台-小游戏-API-其他说明）相关说明。
Q：
开发者工具上接口表现与真机不一致
A：
开发者工具的小游戏模拟器是在 PC 上模拟宿主行为、方便开发者进行简单调试的方案，表现上更接近 Web 浏览器，且对于广告、支付、登录态相关接口的模拟无法完全对齐真机表现。真机客户端上出于安全、性能考虑有更多的限制，也会有更完整、流畅的体验，实际表现请以真机客户端为准。
Q：
小游戏在开发者工具上的缓存目录、沙盒目录
A：
小游戏包本地路径、IDE 目录（缓存及沙盒目录）可见开发者工具右上角「详情 / Detail」入口，其中的「基本信息 / Basic Information」栏中，有对应的目录罗列且可以直接打开。每次小游戏工程载入运行会有一个唯一的 session，通过 tt.downloadFile 等接口下载、产生的文件也会在此沙盒环境上存储。
二、关于
开发者平台
Q：
域名白名单配置错误
A：
请参考网络请求（抖音开放平台-小游戏-普通小游戏开发-框架-基础功能-网络请求）说明文档，检查配置的域名白名单是否符合条件。
常见的问题：
1.配置的链接不能具体到接口路径：https://baidu.com/path
2.配置的链接不能带上端口号：https://baidu.com:8080
Q：
域名白名单配置无权限
A：
域名白名单需要管理员，拥有者才能配置。
Q：
域名配置数量上限
A：
每种协议的域名白名单可以配置200个，有特殊需求需要超过规定限制的小游戏请联系官方客服。
Q：
虚拟支付服务器回调地址检查错误
A：
请参考虚拟支付服务端回调（抖音开放平台-普通小游戏开发-API-支付-服务端回调接口），检查填写的服务器回调地址是否符合条件。
常见问题：
1.填写的回调地址不是一个外网可访问的链接；
2.填写的回调地址返回的 echoStr 格式错误，预期应该是返回字符串，而不是 JSON 。
Q：
选择银行时查找不到指定银行
A：
请先选择开户银行再查找开户支行，支行无法查到的请更换关键字再次查询，如果还是查找不到再联系官方客服。
Q：
抖音号绑定失败
A：
请参考游戏关注内抖音号能力（抖音开放平台-小游戏-规范-抖音号内关注抖音能力），绑定时检查「前置条件」和「绑定规则」是否满足，尤其注意个人抖音号需要完成实名认证，企业抖音号需要保证小游戏主体资质（统一社会信用代码）与抖音企业号认证主体资质一致。
Q：
自定义事件测试不通过
A：
通常不通过原因是因为上报数据类型和设置的数据类型不一致，测试不通过不会影响数据的上报。
三、关于
API或组件
Q：
xxx fail must be invoked by user gesture
errMsg: xxx fail must be invoked by user gestureA：
出现该错误是因为小游戏框架对一些 API ，比如tt.requestSubscribeMessage、tt.shareAppMessaged 的调用存在限制，这些 API 必须由用户点击触发。
以具体代码为例：
tt.requestSubscribeMessage({...}) // 直接调用，会报错 ... must be invoked by user gesturett.onTouchEnd(()=>{ tt.requestSubscribeMessage({...}). //正确调用})注意：必须保证是在 tt.onTouchEnd 的回调里面同步调用，其他比如 tt.onTouchStart 也会报错。
对于使用第三方引擎开发的开发者来说，一般只要保证这些API是在引擎对应的触摸事件里面处理调用即可。
Q：
测试版本没问题，
但是线上版本就有问题
A：
这种大部分情况是白名单配置导致的，可以检查后台白名单配置。也可以在开发时候，选择开启IDE中的校验域名白名单，保持和线上环境一致。
Q：
广告返回报错 1003 或 1004
A：
该为正常报错，代表当前没有合适的广告。开发者侧需要做好拉不到广告的逻辑处理，不影响游戏正常进行即可。
Q：
图片显示问题｜想要显示用户头像，但发现头像域名会有很多种，在后台配置域名白名单感觉无法覆盖？
A：
请直接使用 tt.createImage （抖音开放平台-普通小游戏开发-API-渲染-图片-tt.createImage）来负责图片的显示，该API 去显示网络图像时，不会进行域名白名单的校验。
Q：
tt.requestGamePayment 返回-15002 参数错误
A：
最常见的错误原因是：buyQuantity * 游戏币单价 = 限定价格等级 这一条件没有满足，具体限定价格等级可见 tt.requestGamePayment （抖音开放平台-小游戏-普通小游戏开发-API-支付）。
Q：
如何区分微端和桌面快捷方式场景？
A：
通过接口 tt.getLaunchOptionsSync（抖音开放平台-普通小游戏开发-API-系统-生命周期）获取 launch_from 字段来细分微端场景。
记得关注【mini游戏情报局】喔！