Unity转抖音小游戏重点摘记

本文由 NRatel 历史笔记整理而来，如有错误欢迎指正。

一、接入指南

Unity 小游戏接入指南_抖音开放平台

免安装沙盒运行、小包化技术

WebGL方案 android和ios 都支持

使用 Unity2021+（至少） 支持 ASTC

不支持非托管代码、Android/iOS原生代码、性能受限（低于原生）

需要调整 网络系统 和 文件系统

构建与调试

BGDT （ByteGame Developer Tools）

安装_抖音开放平台

下载，以 unitypackage 方式存在

如：com.bytedance.bgdt-cp-3.0.271.unitypackage

导入后，从Unity 菜单栏选择：ByteGame => StarkSDKTools => Build Tool 打开

运行框架可选：

1. Android Native构建（缺点：仅支持安卓）
2. WebGL构建（优点：同时支持安卓和IOS；缺点：性能是Native的1/3）

发布

需使用 抖音开发者工具 发布

开发者工具正式版下载_抖音开放平台开发者工具正式版下载,* *4.4.4（2025-08-21） *新增：支持智能调整服务端模式，支持一键生成带有服务端代码的小程序应用，查看详情 *新增：新增智能调整切图功能，支持输入图片时自动识别内容并切图，查看详情 *修复：修复开发者工具偶现网络请求不稳定及工程打开缓慢问题 *修复：修复二维码解析https://developer.open-douyin.com/docs/resource/zh-CN/mini-app/develop/dev-tools/developer-instrument/download/developer-instrument-update-and-download

1、从 ByteGame => StarkSDKTools => Build Tool 点击 【开发者工具发布】 按钮，跳转至抖音开发者工具，抖音开发者工具将自动将Unity工程导入。

2、登录抖音开发者工具，点击左上方【上传】按钮即可进行发布操作。

3、选择右上方【详情】按钮，可选择发布方案、产物、胶囊按钮颜色和屏幕方向等信息。（工程配置）

4、支持多项目并行测试（同时25个测试版本）。

5、支持 CLI 指定测试通道上传

抖音开放平台undefined,undefinedhttps://developer.open-douyin.com/docs/resource/zh-CN/mini-game/develop/dev-tools/developer-instrument/development-assistance/ide-cli

其他

1、可从project.config.json 或 音开发者工具右上方的详情处修改 appId

2、可点击抖音开发者工具工具栏的测试二维码按钮获取最近一次发布的Unity小游戏二维码，开发者可使用抖音客户端扫码查看效果​

3、在版本4.0.2之后，StarkSDKTool将不再支持发布能力，开发者请尽早将发布能力迁移至抖音开发者工具

测试环节

发布成功之后，被发布的游戏版本会自动进入测试环节

登录 小程序开发者平台，跳转至 【版本管理 】进行测试。​

测试完毕后，点击【提交审核】来进入审核环节。具体请参考：审核指引

审核环节​

提交审核后，进入审核环节。​

登录 小程序开发者平台，跳转至 【版本管理 】进行查看。​

审核通过后可进入发布环节。​

发布环节​

版本审核通过后，开发者点击“发布”，小游戏即可发布上线。​

登录 小程序开发者平台，跳转至 【版本管理 】，找到审核通过的游戏，点击【发布】​

CI 自动化

利用Unity的batchmode，调用 StarkSDKTool.API.BuildManager

使用 StarkBuilderSettings.Instance 进行构建前设置

CI自动化_抖音开放平台CI自动化主要是通过提供开放API供开发者接入来实现的。开放API从配置，构建，以及发布三个方面提供了OpenAPI,*配置 配置接口提供了丰富的配置选项，开发者可根据需要进行相应的配置。另外对于配置接口中的配置项与以下构建或者发布接口中参数项冲突时，以接口内的参数为准。 *获取配置对象 *WebGL构建相关 配置项均在TTSDK.Tool.StarkBuilderSettings.Instanhttps://developer.open-douyin.com/docs/resource/zh-CN/mini-game/develop/guide/game-engine/rd-to-SCgame/unity-game-access/ci_openapi

C# SDK

基于接入的 BGDT unitypackage

C# SDK 接口文档_抖音开放平台

兼容性检查接口（低版本不支持的API）

StarkSDKSpace.CanIUse.xxx

必接功能

广告、录屏、绑定抖音号、创建快捷方式、分享、登录、支付、打开客服页、自定义事件、敏感词过滤。

C# SDK 发版记录

https://developer.open-douyin.com/docs/resource/zh-CN/mini-game/develop/guide/game-engine/rd-to-SCgame/unity-game-access/sc_changelog

目录说明与缓存策略

1、Application.persistentDataPath 游戏文件目录的可写路径。
注意，部分开发者会将游戏存档放在游戏文件目录，该目录并不保证长期存在，建议使用玩家数据目录；​存储上限1GB。

2、Application.temporaryCachePath 游戏临时目录的可写路径。该目录会在游戏未使用时，随时清空。请不要在该目录中放置任何重要的数据文件，以免丢失导致玩家损失。临时目录没有存储上限；但是注意，一旦游戏退出，随时可能会被清空。​

3、玩家数据目录​

玩家数据目录，是用于放置用户需要长期存储的数据资产的，主要用于放存档文件。游戏存档目录不会被磁盘清理机制所清理，会长期保留在磁盘上。​

开发者无法直接获得玩家数据目录的路径，而是可以通过StarkSDK提供的Save/Load接口对数据对象进行存取操作，存取的结果会保存在玩家数据目录中；具体用法可以参考StarkSDK_Unity文档 ；​

除此之外，如果只是简单的key-value存储，也可以使用Unity提供的PlayerPrefs接口进行数据存取；​

玩家数据目录的存储上限为50M，如果达到上限，写入操作会失败，可以使用提供的配套接口删除不需要的存档文件。​

FAQ

FAQ_抖音开放平台

接口demo ​

https://sf3-g-cn.dailygn.com/obj/sf-game-lf/testgn/StarkSDK-Sample.zip

注意控制包体 100M以内

二、C# API 文档

抖音开放平台

初始化：初始化

开放能力：账号、侧边栏、收藏、群聊、平台开放能力、直玩能力、游戏互推组件、好友排行榜、数据分析、客服能力

基础：兼容性判断接口、版本更新

设备：加速度计、剪切板、屏幕亮度、震动、陀螺仪、方向监听

文件：获取文件管理器、文件管理器

媒体：录屏

网络：发起请求、UDPSocket

游戏分享：分享模块

数据缓存：数据缓存

系统：版本号、获取系统信息、游戏生命周期、获取小游戏启动参数、退出重启、触摸事件

界面：键盘处理器、敏感词

支付：支付接入、支付请求、游戏金币（仅抖音lite）

广告：激励视频广告、Banner广告、插屏广告

宿主事件：宿主事件监听

抖音云模块：抖音云

邀请模块：邀请模块

PlayerPrefs：PlayerPrefs

调试工具：调试工具

三、WebGL 方案与优化

WebGL适配方案_抖音开放平台

技术原理

WebGL适配方案概述_抖音开放平台

性能大概是Native的 1/3​

在iOS上内存很受限制，代码分包是必要优化（Wasm分包工具）

支持 内置管线和URP

支持托管类型的dll插件、C#源码插件，不支持非托管类型（如C++编译的）dll

不允许热更（1、政策不支持、2、性能急剧下降）

支持 协程/async/await​

不支持多线程

需调整网络接口

WebGL方案上iOS​

先考虑清楚：优化的不好，用户的加载时长高，取消率高，使用时长短，可能对整体分发（包括android用户）有负向效果​

当前ios系统限制，对性能要求较高。为了用户更好的体验，所以对iPhone XR以下机型没有打开可见性入口​

ios上的录屏功能会有权限申请，还有性能消耗，不建议使用。一定要使用，dau达到10w后，跟平台运营同学联系开白名单。（平台只要求android上要录屏分享）​

WebGL接入流程
python -m http.server -d index.html所在的目录路径 8080 (端口号随便定，有效就行)

使用浏览器打开测试

注意：在浏览器下无法测试广告能力，广告功能只能在抖音下运行

测试环境右下角有一个按钮【vConsole】，线上版本不会出现这个按钮。​

目前Unity编译出来的WebGL版本默认不支持中文，需要单独放一个中文字体库。​

可以自行找一个喜欢的并支持中文的字体库。也可以下载下面这个中文字体库：​

WebGL方案接入流程_抖音开放平台

WebGL不支持动态库，如有使用so，需找到webgl版本替代。​

iOS上运行WebGL发热比较厉害，建议限帧运行。Application.targetFrameRate 建议值为22~30之间。​

WebGL2.0支持情况：iOS支持15.0及以上系统，Android WebGL2.0支持。​

性能优化

性能优化总览_抖音开放平台

加快启动速度

资源按需加载

降低内存占用

减少cpu消耗

性能评估标准

抖音开放平台

WebGL 方案优化建议

WebGL方案优化建议_抖音开放平台

四、资源相关（重要）

1、使用 TTAssetBundle优化内存

抖音开放平台

在Unity WebGL 小游戏环境中处理 AssetBundle 加载时，无法使用 AssetBundle.LoadFromFile，而是需要使用UnityWebRequest 等通过网络的加载接口。

而通过 UnityWebRequest 加载 AssetBundle 时，下载或从本地缓存中读入的 AssetBundle 文件会完整拷贝到 Unity Heap 内存，在 Unload 之前额外占用 Unity Heap。而由于 Unity Heap 一旦超额分配便无法从 JS Heap 中释放，将其控制在更小范围内有利于控制整体进程内存，降低崩溃率。​

解决方案：

TTAssetBundle 接口通过打通 Unity 内存文件系统和小游戏本地缓存文件系统接口，在加载 AssetBundle 时内部使用 LoadFromFile() 仅打开文件流，在 LoadAsset 时通过文件描述符按需读取 AssetBundle 的包内资源，可以节省与 AssetBundle 文件大小相当的内存。

在不支持的版本/宿主上，会 fallback 为类似原本 UnityWebRequest 加载实现，仍可正常加载到资源。​

using StarkSDKSpace;UnityWebRequest request = TTAssetBundle.GetAssetBundle(url);
yield return request.SendWebRequest();
if (request.result != UnityWebRequest.Result.Success)
{Debug.Error(request.error);
}
else
{AssetBundle ab = (request.downloadHandler as DownloadHandlerTTAssetBundle)?.assetBundle;ab.TTUnload(true); // 使用 TTAssetBundle 加载的资源，必须调用 TTUnload() 方法才可彻底卸载。
}

TTAssetBundle 的卸载规则​

◦​加载过程中的 AssetBundle 文件会在 JavaScript 内存中保留一份完整的文件缓存以保证载入性能。​

◦​内存文件缓存中的文件超过 5s 未被读取或缓存占用超出 128MB 上限时，将按 LRU 清理最久未被读取的 Bundle。被清理的 AssetBundle 下次读取时将重新从磁盘读入，建议开发者及时调用 TTUnload() 卸载不使用的 AssetBundle。自动清理的阈值支持在 StarkBuilderSettings 中配置。​

AssetBundle的简单例子​

//方式1
UnityWebRequest request = UnityWebRequestAssetBundle.GetAssetBundle(uriPath);
yield return request.SendWebRequest();
AssetBundle ab = (request.downloadHandler as DownloadHandlerAssetBundle).assetBundle;//方式2
UnityWebRequest www = new UnityWebRequest(uriPath);
DownloadHandlerAssetBundle handler = new DownloadHandlerAssetBundle(www.uri.ToString(), 0);
www.downloadHandler = handler;
yield return www.SendWebRequest();
AssetBundle ab = handler.assetBundle;

跨域问题：，我们在JS层重写了网络请求相关的部分，用户在不修改任何C#层的代码的前提下，可以正常支持跨域请求。​

代码加载优化Wasm分包

抖音开放平台

定制启动封面

小游戏资源部署与缓存

资源缓存

首包资源包含 wasm 代码文件、StreamingAssets 文件夹等内容。

远程资源则以开发者自行托管在 CDN 上的 AssetBundle 文件为主。通常在游戏内按需下载，根据配置保存到缓存。

菜单栏 - ByteGame - StarkSDKTools - Build Tool 配置缓存域名

//检查资源是否已被缓存​
TT.GetFileSystemManager().IsUrlCached(string url);
​
//​获取缓存资源的本地路径​
TT.GetFileSystemManager().GetLocalCachedPathForUrl(string url);
​
​//手动删除对应的缓存文件​
TT.GetFileSystemManager().UnlinkSync(string path);

静态更新​

每次打开Unity小游戏时都会检测并更新到最新版本。​

游戏新版本发布后，重新进入游戏即为最新版本，特殊情况可能会有几分钟延时的情况。​

​

动态更新​

游戏运行期间有新版本，目前还不能感知。

WebGL2.0支持

Android平台已经完成对WebGL2.0的适配支持。

iOS15.0及以上系统已支持。​

StarkSDKUnityTools中​勾选WebGL2（beta），并打包发布。​

因现Android WebGL2.0已经全量，无需点击该按钮“加入WebGL2.0测试白名单”，直接勾选“WebGL2（beta）”即可。​

Unity 音频​

在 WebGL 方案中，Unity 音频能力从 ​Unity 2021、StarkSDKUnityTools 3.1.0​​开始正式适配：​

多点触控适配

UGUI 在 Unity 场景内找到 EventSystem，挂载 StarkInputOverrideBypass 组件。​

外部js支持

加载外部js文件的支持_抖音开放平台

新文件系统

StarkFileSystemManager 用于优化内存

屏幕适配

获取安全区域方法 StarkSDK.API.GetSystemInfoSync

键盘输入法适配

在 Unity 小游戏环境的 WebGL 方案中，支持 Unity 2022 及以上版本 Input Field 组件自动适配键盘输入法，无需手动调用。低版本或其他组件暂不支持。​

后端服务指引

后端服务指引_抖音开放平台

网络通信​

Unity WebGL 中，HTTP 需使用 UnityWebRequest 类。​

Unity WebGL 中，TCP 需使用 WebSocket。​

Unity WebGL 中，UDP 需使用 SDK 提供的 UDPSocket 进行替代