快速上手

我们以Endless Runner游戏为示例，介绍如何一步步操作将游戏发布到微信小游戏平台，示例工程可从以下链接获取EndlessRunner。

1. 新建工程

新建工程Endless Runner，下载EndlessRunner并导入工程。

2. 适配纹理格式（ASTC）

打开项目切换到WeiXinMiniGame平台，在BuildSettings页面将Texture Compression改为ASTC并保存，首次切换ASTC会转换Texture压缩格式，需要较长的时间。 开启ASTC压缩后，小游戏在移动端运行时可以节省大量内存和显存。

3. 配置Graphics API

在ProjectSettings/Player/WechatMinigame/Other Settings页面，取消勾选Auto Graphics API，仅保留WebGL 1 或者WebGL 2。可以减少shader变体数量，从而减小首包和启动时间。

使用WebGL 1时， 若Lightmap Encoding为High Quality，将其改为Normal。

** iOS平台上使用 WebGL 2.0 需要系统版本高于15.0，并且打开iOS高性能模式。 ** 否则可能出现进入游戏后白屏的情况。

4. 安装InstantGame Package

• 打开Package Manager，选择Unity Registry, 然后搜索“instant game”, 点击“install”安装以下package最新版本:

如果在PackageManager中无法搜索到，请在项目的Packages/manifest.json文件中直接添加以下package: "com.unity.instantgame": "1.0.6"

5. 配置AutoStreaming功能

InstantGame窗口位于Windows → Auto Streaming，该窗口包含了打包小游戏前的资源Streaming设置，以及上传云资源到UOS CDN的设置。

• 切换到Cfg & Publish窗口，勾选Use AutoStreaming，如果后续需要使用正常的打包流程，取消勾选该选项即可。

• (可选)勾选Use Font Streaming，开启字体资源的Streaming。

• Cache Texture AB in Memory，将下载的Autostreaming原始纹理AB缓存在内存当中，以减少纹理模糊的时间， 会明显提升内存使用。

• Max Cocurrent Load， 设置AutoStreaming最大后台下载和加载任务数量，允许的值是0–20，值为0时，使用引擎默认值。

6. 配置UOS CDN服务

小游戏AutoStreaming功能默认使用UOS CDN作为部署streaming资源的云服务器，分离的资源将被托管至 UOS CDN服务。UOS 在CDN基础上提供了便捷的云端资源的版本管理。

字段	描述
App ID	UOS应用标识字符串；
App Service Secret	UOS应用的认证密钥；该字符串作为上传UOS CDN文件的钥匙，请注意保密;
Bucket	文件桶，一个游戏对应一个bucket，利用UOS CDN资源版本管理和增量上传的优势可以提高开发效率；
release	发布版本，AutoStreaming每次上传文件到UOS CDN，都会创建一个云服务器文件的release；
Badge	Badge作为release的别名，用于固定资源下载的url；每次发布小游戏新版本时，务必创建一个新的Badge使用。

• 前往Unity Online Service 首页，进入应用面板，点击 ** + ** 新建应用，创建一个名为 Endless_Runner 的项目，然后启用UOS（如已有 Endless_Runner项目可直接启用UOS）。

• 完成后网页将自动跳转到项目的概览页面，点击右侧的CDN 免费试用按钮开启CDN功能。

• 从设置页面获取UOS App ID和App Service Secret并填写到Cfg & Publish窗口的对应输入框中 ，完成后单击左栏Refresh按钮拉取Endless_Runner的Bucket/Badge 信息。

• 选择或者创建新的Bucket/Badge 并使用。在这里Endless_Runner是一个新建的项目，当前并不存在bucket和badge，因此我们新建一个名为Endless_Runner的bucket，并在该bucket下新建一个名为v1的badge。

UOS CDN会为每一个Bucket自动生成一个名为latest的badge，每次上传文件，该badge位置都会自动更新，始终指向最新的资源版本，因此不要在提交给小游戏平台的版本中使用latest，以免后续资源更新时影响已发布版本。

7. 配置资产列表[此案例跳过]

在具体配置AutoStreaming之前，引擎需要知道哪些资产是当前游戏正在使用的。 大多数情况下，引擎AutoStreaming 工具能够自动找到这些资产。 但通过BuildPipeline.BuildAssetBundles(string outputPath, AssetBundleBuild[] builds, …)从代码中打包的AB，无法被AutoStreaming自动搜索到，因此需要用户额外提供一个自定义AB中所有资产的列表文件。 可前往资产搜索和引用标签页面查看如何生成和设置资源列表文件。

Endless Runner游戏工程中没有使用该方式打包AB，因此跳过该步骤。

8. 配置Texture Streaming

配置游戏内Texture是否使用Streaming功能，以及Streaming Placeholder的类型。AutoStreaming用Placeholder图片替换游戏首包内的原始贴图，游戏运行时，先加载低分辨率/低信息量的贴图，快速启动游戏。当游戏首次使用到该Texture资源时，将触发引擎后台线程从UOS CDN云端下载原始贴图，完成后自动替换为原始贴图。

功能	描述
Sync Texture	搜索 BuildSettings 中的 Scenes 引用到的所有 Texture 资源；
Force Rebuild	勾选后点击Generate AssetBundles，将强制重新生成 texture 的 AssetBundles；
Generate AssetBundles	为所有勾选的 texture 生成 AB，每张贴图一个 AB；
Generate Placeholders	为所有勾选的 texture 生成一张低分辨率的替用贴图；也可以选择生成透明或者模糊形式；
ConvertLegacySpritePacker	将旧式的Sprite packer 图集转换成SpriteAtlas，从而获得Streaming支持；该功能会清理所有Sprite上的Packing Tag，使用前请对工程做好备份。
Use SpriteAtlas Placeholder in Addressable	游戏中使用了图集并且打包到了Addressables中，将替换其中的图集为更小的variant图集。

首次打包操作流程：点击 convertLegacySpritePacker(可选) → Sync Texture → Ctrl + A 选择所有图片，勾选 OnDemandDownload → 点击 Generate AssetBundles → 点击表头按生成的AB大小排序，取消勾选 AB 过小的图片（例如小 5KB，可按住Shift多选） → 点击 Generate AssetBundles清理不需要的AB → 点击 Generate Placeholders。

更新操作流程： Sync Texture → 调整OnDemandDownload的勾选 → 点击 Generate AssetBundles重新生成AB → 点击 Generate Placeholders。

最新版本团结已支持增量打包，能够显著提高打包效率。如果需要也可以勾选Force Rebuild，强制全部重新打包。

注: 如果游戏中使用了图集SpriteAtlas，并且图集打包到了Addressables中，请在上述操作完成后，需要额外点击按钮 “Use SpriteAtlas Placeholder in Addressable”来替换其中的图集为小图。

9. 配置Audio/Mesh/Animation Streaming

配置游戏内的Audio/Mesh/Animation资源是否使用streaming功能。AutoStreaming支持将本地较大的音频和 mesh等资源内的数据从游戏首包/AB 中抽离出来，部署UOS CDN服务器上。当游戏首次使用到该Audio/Mesh/Animation资源时，将触发引擎后台线程下载资源数据，完成后自动加载使用。

使用流程：点击 Sync Audios/Meshes/Animation → 勾选 RT Mem 较大（例如大于5K）的资源。

如果某个Audio/Mesh/Animation勾选了Streaming导致游戏出现问题（勾选Streaming会使Audio/Mesh的数据延迟，在代码中对该Audio/Mesh进行了读写操作， 可能出现问题），取消勾选该 Audio/Mesh/Animation 即可。

10. 配置场景Streaming

选择BuildSettings中的场景打包成 AssetBundle，并部署到UOS CDN服务器上。开发者像往常一样通过 SceneManager 调用 LoadScene 或 LoadSceneAsync。底层将自动触发下载，完成后自动加载场景。 详细信息可前往使用Auto Streaming按需加载页面Scene小节了解。

功能	描述
Sync Scenes	获取 Build setting 中的Active的所有场景，并在下方显示；
Force Rebuild	勾选后，点击Generate ABs时将强制重新生成所有场景的AB；
Generate AssetBundle	生成场景的AB，以及场景共享资源AB;
Sync SharedAssets	搜索勾选了Streaming的场景中的共同引用到的资源。

Scenes 列表中建议勾选除首场景外的其他所有场景，首场景开启Streaming后，启动时会有明显的黑屏时间，因此不建议勾选。

Shared Assets列表中，建议仅勾选对场景AB总量影响严重的资源，并且尽量排除FBX文件，如：

• 被大多数场景引用到的资源(References中包含场景序号较多的资源)

• 本身较大的Shader、字体等资源

使用流程： Sync Scenes → 选择需要Streaming的场景 → Sync SharedAssets → 勾选SharedAssets资源 → 如果已经生成过场景AB，勾选Force Rebuild → Generate AssetBundles。

Scene Streaming 依赖于 Texture/Audio/Mesh/Animation/Font Streaming的配置，请务必先执行前面的操作。

11. 重新打包AB/Addressables

游戏中如果存在以下使用情况，需要在配置好Texture/Audio/Mesh/Animation Streaming后完全重新打包（删除已有AB后打包），从而抽取出AB中的重度资源（纹理、网格等）：

• 游戏工程使用了Asset bundle

• 游戏工程使用了Addressables

AB/Addressables中的资源抽取依赖于 Texture/Audio/Mesh/Animation/Font Streaming的配置，请务必先执行前面的操作。

由于WebGL不存在本地文件，因此所有的AB/Addressables和都需要上传到CDN，运行时通过网络下载。 而下载需要时间，因此游戏逻辑中通常需要支持异步加载AB的，或者提前准备好所需AB，这与是否使用AutoStreaming方案无关，详细介绍请参考平台特征介绍中文件系统和网络小节。

如果项目有用到AB或Addressables，且文件并非存放在StreamingAssets目录，则需要在AB/Addressable后增加一次文件拷贝操作，请参考UOS上传和下载文件了解详细操作。

Endless Runner游戏工程使用了Asset bundle进行资源打包，在这里将重新打包AB，需要注意将打包平台修改为BuildTarget.WeixinMiniGame或EditorUserBuildSettings.activeBuildTarget。 由于切换到了新的平台WeiXinMiniGame，因此需要在Assets\AssetBundleManager\Utility.cs的GetPlatformForAssetBundles方法中添加该平台：

    #if UNITY_EDITOR
        private static string GetPlatformForAssetBundles(BuildTarget target)
        {
            switch (target)
            {
                ...
                case BuildTarget.WeixinMiniGame:
                    return "WeixinMiniGame";
                ...
            }
        }
    #endif

        private static string GetPlatformForAssetBundles(RuntimePlatform platform)
        {
            switch (platform)
            {
                ...
                case RuntimePlatform.WeixinMiniGamePlayer:
                    return "WeixinMiniGame";
                ...
            }
        }

然后按照以下步骤打包：

• 如果已经打包过AB，删除StreamingAssets目录下的AB包

• 点击 AssetBundles -> Build AssetBundles 重新打包AB

Endless Runner项目将AB打包到了StreamingAssets目录下，该目录的上传已由AutoStreaming工具自动化处理。这里我们不考虑版本更新问题，因此打包AB时未使用带hash的文件名。

12.配置CDN http 协议版本（可选）

如果有使用HTTP/2或HTTP/3协议的需求，请前往UOS CDN网站，找到游戏使用的项目和bucket，点击右上角的三个小点， 选择开启HTTP/2 传输 或者 开启HTTP/3 传输。

• 开启后注意按照步骤20中的提示添加域名白名单，否则真机运行将提示下载失败。

13.安装微信开发者工具

前往微信官方网站下载微信开发者工具， 并安装到本地PC上。

14.添加微信小游戏转换SDK

推荐以git URL方式添加：点击下图位置，填入： https://github.com/wechat-miniprogram/minigame-tuanjie-transform-sdk.git 。

也可以直接下载微信小游戏转换SDK插件，并导入工程。 此方式完成后可以看到在游戏工程assets文件夹下 有 WebGLTemplates 和 WX-WASM-SDK 这两个新增文件夹。

由于微信SDK中调用了WebGL平台下的brotli压缩工具，因此安装团结引擎微信小游戏平台时，请同时安装WebGL平台

15.配置微信小游戏导出参数

打开微信小游戏 -> 转换小游戏页面。在这里有以下几个参数需要填写：

• 游戏appid： 可从微信小游戏开发工具里点击register去申请正式appid，使用测试appid部分功能受限

• 游戏资源CDN： 游戏资源CDN根目录。使用AutoStreaming自动填充，其余情况需填写

• 小游戏项目名称： 导出的微信小游戏项目名称

• 游戏方向：横竖屏，根据游戏画面选择

• 导出路径： 生成微信小游戏工程的位置，后续步骤需要打开其中的小游戏目录

16.导出并转换成微信小游戏

由于Scene和Texture的AutoStreaming文件会在上传前计算hash并保存在首包中，打包前请先确认AutoStreaming页面TextureStreaming->Generate AssetBundles 和 Scene Streaming->Generate ABs操作已执行。

在转换小游戏界面里点按钮 “生成并转换” 开始打包，该步骤需要5min左右。如果使用了AutoStreaming，完成后会自动上传首包数据文件到UOS CDN。

如未使用AutoStreaming，请将首包数据文件上传到微信小游戏页面填写的{游戏资源CDN}根目录。 如果有填写“Data File Sub Prefix”字段，则上传到该子目录下。

打包时如果遇到下面的报错，请确认安装了node js， 并且在系统环境变量的path中添加了node js安装路径。添加在用户环境变量path下可能无效。

17.在微信开发者工具中打开工程

打开微信开发者工具，选Mini Game工程类型，然后点import按钮，选择步骤16中生成的wechat/minigame文件夹。注意不要选错目录。

18.在微信开发者工具中测试

微信开发者工具打开小游戏工程后，游戏将自动开始运行；打开Simulator和Debugger，以查看游戏画面和调试信息。点击右侧Compile按钮，可以重新启动小游戏。

微信开发者工具中运行时，如果出现 “插件未授权使用 添加插件”的错误提示，请点击“添加插件”按钮， 并且确认是否使用了测试游戏appid。

CDN如果未开启gz/br压缩，在微信开发者工具的log中将有如下提示：

UOS CDN gzip/br压缩可通过accept-encoding控制，微信小游戏已自动添加“gzip,deflate,br”，因此无需额外操作。

19.在手机上测试

开发版本： 微信开发者工具 上点preview 生成二维码 扫码 后，可以在手机（同一微信账号）上测试， 如果需要分享二维码给其他人，需要申请正式的小游戏appid，并在微信后台添加测试人员的微信账号。

体验版本： 使用正式的小游戏appid打包的小游戏，可以点击右侧Upload按钮，填写版本号和版本描述，上传体验版本。然后在微信小游戏后台管理/版本管理/开发版本中找到上传的版本，将其设置为体验版。该版本后续可用于提审发布。

如果遇到资源下载失败，404的错误。请点开手机右上角三个小点，找到并打开 开发调试->打开调试。或者按照步骤20，在微信小游戏后台添加白名单。

20.添加域名白名单

扫码登录微信小程序网页后，前往开发管理-> 开发设置 -> 服务器域名 在request合法域名 和 downloadFile合法域名中填写用到的域名。 如果游戏中使用到了其他类型的网络链接，如websocket，需要在socket合法域名内填写。

AutoStreaming使用到的域名： 请填写以下域名： https://a.unity.cn; https://a.unity3dcloud.cn; https://asset-streaming-content.unity.cn;

开启http/2 或 http/3后需添加以下域名： https://a2.unity3dcloud.cn; https://a3.unity3dcloud.cn;

 

如果项目工程中引用了Analytics Package，小游戏运行时可能出现cdp.cloud.unity.com, cdp.cloud.unity.cn 或 cdp.tuanjie.cn等域名的请求。 请前往Windows -> General -> Services关闭， 并且在PackageManager中移除Analytics。