Unity发布京东小游戏全流程：从WebGL适配到真机踩坑实录

前阵子我们一款休闲闯关游戏需要做新渠道发行，业务方给的其中一个需求就是“跑进京东 App 里的小游戏容器”。我先入为主地以为这事跟微信小游戏差不太多——毕竟当年已经给微信做过一轮 Unity WebGL 到小游戏的适配，无非是换个平台再对一遍接口。等真把京东的开发文档翻完、把一个能跑通的 Demo 跑出来之后，我才意识到这类工作最花时间的地方根本不在 Unity 本身，而在于你对目标宿主环境了解多少。

这篇就是我从头到尾做“Unity 发布京东小游戏”的完整记录，涉及基础运行原理、Unity 工程改造、构建产物处理、平台接入、真机调试和一堆实际踩坑。目标读者是已经会 Unity、但第一次接触京东小游戏或各电商小游戏平台的开发者。文章不会替你写好所有业务代码，但会把你最容易在文档里遗漏、或者很晚才发现真机的流程全部提前讲清楚。

1. 京东小游戏的技术栈和 Unity 的关系

1.1 Unity 小游戏的底层运行方式

先说原理。Unity 本身并不直接支持“京东小游戏”这个输出目标，Unity 侧的标准做法是先把游戏导出成 WebGL 项目，再把 WebGL 产物放进小游戏容器里运行。

Unity 的 WebGL 导出一共会生成几类关键文件：编译后的 WebAssembly 字节码（对应 C#/IL2CPP 编译出的逻辑）、Unity 运行时框架 JS、资源 Data 文件以及加载器。渲染走的是 WebGL，音频、网络、存储这些则依赖宿主环境提供能力。

原本 Unity 的 WebGL 产物是要跑在浏览器里的，但小游戏容器并不是完整浏览器。它是一个裁剪过的 JS 环境，可能没有 windows、document 完整实现，也不能直接让你访问 file:// 来读写本地目录。所以京东小游戏这类平台，需要用一层“适配层”把 Unity 运行时代码里调用的浏览器能力，映射到小游戏平台提供的 JS API 上。

这也是我建议所有第一次做小游戏的人先去弄明白的第一件事：Unity 到小游戏，不是一个“换平台重新发布”的按钮操作，而是 Unity WebGL + 宿主适配 + 平台 API 接入三层结构的整合。只要这一层概念清楚，后面遇到 whitelist、DllNotFoundException、资源路径打不开之类的问题，基本都能自己推出排查方向。

1.2 京东小游戏和其他小游戏平台的差异

我们很多人最早接触的是微信小游戏，于是习惯性地会想“京东应该也差不多”。实际动手后发现，京东小游戏在自己的宿主环境划分、API 命名、开发工具和审核要求上都有独立方案，不能直接平移微信项目的代码。

我做一个简化对照，方便你有整体认知：

这段想表达的核心是：你在微信上踩过的坑有参考价值，但每个平台的适配层代码、API 能力、包体策略和真机规则都要重新核对。尤其是如果游戏要用到登录、支付、分享、排行榜这类带账号和关系链的功能，一定是平台私有 API，不存在一份代码全部通吃的做法。

1.3 什么样的技术路线最适合京东小游戏

从我这次项目的经验看，最稳妥的方案是：Unity 工程主体不做大改，但把所有平台相关能力收口到一个 SDK 适配层，游戏逻辑通过 C# 接口调用，适配层内部再去映射京东小游戏 API。

这个收口思路很关键。原因也很简单：Unity 工程一般先做 iOS/Android/Web 各端，如果业务里到处直接调用某个平台的 JS API，等到切京东小游戏时会拆到崩溃。而把平台能力封装成“登录、分享、录像、支付、读取图片”几个接口，京东侧只实现一套，别人家的平台也能复用，后续如果要发抖音、快手或者别的渠道，工作量会小很多。

当然，如果你的项目是专门为了京东小游戏从零开发，并且不打算上其它平台，在工程前期直接把平台 API 写进 C# 也行。但我不太建议这样，因为一个小游戏没做起来之前，谁也不知道下个渠道会在哪，适配层能省下的是未来改版的整体成本。

2. 发布前需要做好的 Unity 工程改造

2.1 先锁死 Unity 版本和构建目标

我这次用的版本是 Unity 2022.3 LTS，并且单独安装了 WebGL Build Support 模块。Unity 的 WebGL 能力在不同版本之间差异不小，尤其是资源压缩、异常处理和 IL2CPP 编译行为，所以如果你在维护的是特别老的工程，我的建议是先在项目上线前抽一点时间升级到官方长期支持版本，再用 WebGL 目标单独验证一遍，不要拿生产工程直接切平台。

在编辑器里要做的就是 File > Build Settings，把 Target Platform 切到 WebGL。如果你想用命令行做自动打包，也可以用类似这样的批处理方式：

bash复制/opt/Unity/Editor/Unity -batchmode -nographics -quit \
  -projectPath /path/to/your-project \
  -executeMethod BuildScript.BuildWebGL \
  -logFile /path/to/build.log

对应的 C# 构建方法里只需要简单指定场景和输出目录：

csharp复制public static void BuildWebGL()
{
    var scenes = new[]
    {
        "Assets/Scenes/Main.unity",
        "Assets/Scenes/Game.unity"
    };
    var options = new BuildPlayerOptions
    {
        scenes = scenes,
        locationPathName = "Build/WebGL",
        target = BuildTarget.WebGL,
        options = BuildOptions.None
    };
    BuildPipeline.BuildPlayer(options);
}

注意构建输出的目录名最好不要带中文或空格，否则后面小游戏工具处理路径时很容易出现编码问题。这是很蠢但很常见的坑。

2.2 Player Settings 中直接影响上线效果的几项配置

Unity 导出 WebGL 时，Project Settings > Player 里的参数会直接影响小游戏的包体、首屏速度和稳定性。这里挑几个我实测影响最大的配置说。

第一是 Compression Format。我建议根据目标平台的 WebView 内核支持情况来选，但一般情况下要开启 Brotli，并勾选 Decompression Fallback。如果你在本地用浏览器测试没问题，到小游戏真机上加载失败，优先怀疑压缩格式和宿主的解压能力不匹配。

第二是 Strip Engine Code 和 Managed Stripping Level。在 IL2CPP 编译下，开启 Strip Engine Code 能去掉没被引用到的引擎模块代码，减小 wasm 体量。我这次把 Managed Stripping Level 设成了 Low，避免裁剪太激进导致反射调用丢失。如果游戏里用了第三方插件，建议先用 Medium 或 Low 测试一轮再提包，否则部分功能可能没问题，上了真机却突然报缺类型。

第三是 Enable Exceptions。如果只是线上正式包，可以设成 None 或 ExplicitlyThrownExceptionsOnly 来减少体积。但开发期建议保留 Full，不然一崩溃就是一堆没意义的错误，根本无法定位。

第四是 WebGL Memory Size。这个值决定了 Unity 运行时的初始内存上限，太大会让低端机加载慢甚至闪退，太小又会导致运行中内存不足。经验做法是先按游戏峰值内存观察一段时间，再留 30% 余量。Unity 官方在较新版本里也提供了自动内存增长的选项，但小游戏容器是否完整支持该特性，需要以平台文档和真机表现来验证。

最后提醒一点：如果你同一个 Unity 工程既要出小游戏又要出 Android/iOS 包，WebGL 相关的 Player Settings 和原生平台的 Target API Level 是分开的。热词里提到的“提高 minimum api level 到 API 35”这类针对安卓原生包的操作，不会影响 WebGL 构建，但同一个工程在来回切平台时容易把打包参数搞混，建议把每个平台的设置整理成文档。

2.3 文件系统、存档与网络请求改造

Unity 桌面端开发时习惯了直接 File.WriteAllText 或者用 PlayerPrefs，到小游戏里这些行为需要重新审视。

先说说 PlayerPrefs。在部分小游戏宿主环境里，PlayerPrefs 可能底层没有真正的同步实施，或者数据存在一个你预期之外的位置。如果是比较重要的存档，我建议不要依赖 PlayerPrefs，而是封装一层存档接口，把数据序列化成 JSON 之后通过平台的文件或缓存接口写出去。

这里给一个很粗糙的存档接口示例，主要表达“把宿主差异隔离在接口后面”的思想：

csharp复制public interface ISaveService
{
    string Load(string key);
    void Save(string key, string value);
    void Delete(string key);
}

在京东小游戏环境下实现时，可以调用宿主对象暴露出来的存储能力；在原生环境下则继续用 PlayerPrefs。业务层看不到底层的差异，后续无论换到哪个平台，都只需要换实现类。

网络请求也是一样。Unity 的 UnityWebRequest 在 WebGL 模式下通常会被翻译成浏览器的 XMLHttpRequest 或 fetch，但在小游戏容器里，网络请求必须走宿主提供的请求对象，因为平台需要统一做域名白名单、鉴权和加密协议的处理。所以不要指望 UnityWebRequest 能直接请求任意地址，上线前一定要到平台后台把用到的 CDN、接口域名都配到合法域名列表里，并且全部使用 HTTPS。

2.4 资源与热更选型

京东小游戏对代码包体积有限制，正式环境中代码包放不下太多资源。我的做法是：代码包只放启动场景和必要 UI，实际关卡资源全部打成 AssetBundle 放到 CDN。

这里需要注意选型。Unity 项目里常见的资源加载方式有三种：Resources、AssetBundle、Addressables。如果你的游戏规模不大、追求快速上线，可以考虑一个小的 AssetBundle 管理器；如果项目已经有复杂资源体系，我更推荐 Addressables，它的依赖管理和异步加载比手写 AssetBundle 生命周期要省心不少。

还有一个经常被问的问题：“小游戏能不能热更？”Unity 端的常规热更新方案里，C# 侧反射加载 dll 是被一些宿主环境限制的，而且很多方案依赖 Native Plugin，在 WebGL 下不一定可用。官方语境里的“小游戏”，通常可以接受资源热更，也就是更新 AssetBundle，因为平台把这类资源当数据；但修改逻辑代码的热更范围就受限了，各家平台规则不同，需要以京东开发者文档为准。

我个人的态度是：不要为了热更去引入一个在小游戏 WebGL 环境里根本跑不动的框架，否则最后只能自食其果。先把资源热更跑通，比一开始就想全量代码热更新更现实。

2.5 插件兼容性梳理：尤其小心 DLL 和原生库

Unity 工程往往会挂不少插件，最难受的工作之一就是查“哪些插件能在 WebGL 下运行”。WebGL 是 IL2CPP + WebAssembly，很多插件一开始是按 Windows/Mac/iOS 的 Native Plugin 方式写的，放到 WebGL 目标下会直接编译报错，或者运行时报类似“Unable to load DLL 'slua'”这样的错误。

这类问题的本质是 C# 代码在 P/Invoke，想加载一个原生的 DLL，但 WebGL 环境里根本没有这个 DLL。我的排查流程一般是这样：在 Unity 编辑器里打开 Plugins 目录，逐个查看 PluginImporter 的 Platform 设置，把所有不兼容 WebGL 的原生库取消勾选；如果某个 Lua 热更方案严重依赖原生库，而你要发布小游戏，那么恐怕得提前做方案替换或降级设计。

热词里有人搜“hotfix 是什么东西，在 Unity 里面用到的”，这里顺便说一下：热更解决的是上线后不改包就能更新逻辑和资源的问题，但在小游戏容器里，代码热更要受平台规则约束，资源热更是更主流也更省事的方式。把不必要的高风险热更库从 WebGL 构建里移除，绝对能少走很多弯路。

3. 从 Unity 构建到京东小游戏包的完整步骤

3.1 申请开发者应用和下载官方模板

一个很容易被忽略的问题是前期流程。发布京东小游戏之前，你需要先注册京东开发者账号，创建小游戏应用并拿到对应的 AppID 和密钥。这一步要看具体业务是在哪个开放平台开设，因为京东可能有不同的开发者后台入口，不同部门的小游戏申请链路也可能存在差异。

拿到权限后，从开发者文档里下载官方的“小游戏接入工程”或“Unity 启动模板”。不管平台具体怎么组织目录，一个能接入 Unity 的小游戏工程，至少要有这几样东西：

• 入口文件，用来初始化游戏环境和启动 Unity；
• 全局配置文件，声明游戏名称、方向、屏幕尺寸等信息；
• 适配层脚本或 SDK 脚本，把宿主 API 暴露给游戏逻辑；
• 用于放置 Unity 构建产物的目录。

我在实际接触过的各类小游戏平台中，有叫 game.json 的、有叫 project.config.json 的，也有把适配层封装成 adapter.js 的，总之形态不完全相同。核心是你在开始做工程化之前，先照着官方 Demo 跑通一次，确认目录结构和入口逻辑，再往里面迁移自己的 Unity 产物。

3.2 Unity WebGL 产物怎么整理进小游戏工程

这一步是整个发布链路里最机械但也最容易出错的部分。我先在 Unity 里 Build 出一个干净的 WebGL 目录，构建完后的输出里会看到类似这样的产物列表：

• 一个 HTML 文件，它是浏览器模式下的页面入口；
• Build 子目录，里面包含 .loader.js、.framework.js、.wasm、.data 等；
• 可能还有 StreamingAssets 目录或首场景资源文件。

在小游戏环境里，那个 HTML 文件基本没什么用，因为宿主不是用浏览器打开的页面。我们需要的是把 Build 下的核心文件复制到小游戏的 Unity 目录下，并且让小游戏入口去调用 Unity 的 loader。

一种常见的方式是，在小游戏入口脚本里创建一个 Canvas，设置好宽高，然后调用适配后的 Unity 加载函数，把资源路径指向代码包里的 unity 目录。由于京东宿主环境有自己的对象命名规范，这里我不好直接把对方的 API 写死，但大体伪逻辑类似下面这样：

javascript复制// 入口示例，具体宿主全局对象以京东官方模板提供为准
const canvas = platform.createCanvas();
canvas.width = 750;
canvas.height = 1334;

const unityInstance = platform.createUnityInstance(canvas, {
    dataUrl: "unity/Build/game.data",
    frameworkUrl: "unity/Build/game.framework.js",
    codeUrl: "unity/Build/game.wasm",
    companyName: "your-company",
    productName: "your-game",
    productVersion: "1.0.0"
}, (progress) => {
    // 更新自定义 loading 进度条
});

我建议在工程里保留一个 adapter.js 文件，把 platform.createCanvas、platform.createUnityInstance 这类调用全部放在这里兜底。官方模板如果更新 API，我们只需要改这一个文件，不必翻遍全工程找调用点。这样做对后续多平台发布尤其有用。

3.3 处理启动进度和首屏视觉

小游戏包启动时，Unity 引擎和 wasm 需要时间初始化，玩家看到的一般是平台默认的加载画面。如果你不自定义，很容易出现长时间白屏或黑屏，体验很差。

Unity WebGL 本身提供了加载进度的回调，可以在适配入口里接收。常见做法是在小游戏根节点上自己用 DOM/Canvas 画一层进度 UI，等 Unity 初始化完成后再把它隐藏。如果你设计上要求“首屏先看到品牌 Logo 或背景图”，这部分最好用平台自带的原生界面能力实现，因为它在 Unity 引擎还未启动时就能展示，不会受 WebGL 初始化阻塞。

加载进度回调里尽量不要实时刷文字“xx%”，很多设备上由于性能问题，进度条会一卡一卡，反而让玩家觉得加载很慢。更友好的做法是显示一个平滑动画，等真正的初始化完成之后直接切换场景。

3.4 真机调试、关闭 vConsole、配置合法域名

京东开发者工具一般会提供模拟器、编译、上传等功能，但模拟器不能完全替代真机。尤其是 WebGL 渲染性能、内核兼容性、网络访问这些，只有真机才能暴露出问题。

真机预览时，常见做法是通过开发者工具生成二维码，用京东 App 扫码打开。调试阶段通常会默认打开 vConsole 这类调试面板，方便查看 console 日志。不过线上包必须把 vConsole 关闭，否则玩家端会看到调试浮窗，既影响体验又拖性能。

有些项目在入口脚本里直接用 require 引用了 vConsole，上线时记得删除；更稳妥的做法是通过环境判断来控制：

javascript复制// 示例：仅开发模式注入 vConsole
if (typeof __DEV__ !== "undefined" && __DEV__) {
    require("./vconsole.js");
}

域名白名单这件事，我建议在申请 AppID 之后马上就去后台配好，不要等到真机调试时才弄。因为本地模拟器可能允许不校验域名，但真机预览和线上环境大概率会拦截不在白名单里的 HTTPS 请求。你的游戏如果有 CDN 资源域名、排行榜接口域名、数据统计域名，全都提前列出来填好，否则调试时会出现“本地能用，真机不行”的经典问题。

3.5 上传代码包与提交审核

京东小游戏的正式上线流程，通常是在开发者工具或后台完成代码包上传，然后填写版本号、更新说明，再提交审核。

首次提交前，我会建议自己先把包体大小、启动是否白屏、关键流程是否卡死都过一次。小游戏审核比原生 App 要快，但同样会查基础功能完整性和一些平台规范问题。如果你在游戏里接入了分享、录像等功能，一定要先看平台对调用时机的要求，有些功能不能诱导用户点击或是需要在指定用户动作后触发。

另外，代码包上传之前，记得把开发期的调试入口和明显的日志输出去掉。这里说的不是简单删 vConsole，而是把所有 console.log 全都评估一遍，最好统一通过日志模块控制，避免误输出用户隐私或内部接口信息。

4. 上线路上最容易踩的坑

4.1 常见问题速查表

为了让后面再遇到类似情况的读者能快速定位，我先把遇到频率最高的问题整理成一张速查表：

这个表不是全量问题，但它基本覆盖了从 Unity 工程第一次往京东小游戏搬时最痛的几个现象。每一类问题背后都能写一篇文章，我挑几个实际案例展开说。

4.2 实例一：SLua 的 DllNotFoundException

我们工程早期选用过 SLua 做某些业务逻辑的配置和脚本扩展。第一次切到小游戏真机时，打开控制台就看到红字：Unable to load DLL 'slua'。

排查后确认，SLua 在 WebGL 下不能像 Windows 那样加载原生 slua.dll，因为 WebGL 环境本身不提供这个 DLL。这个报错不一定只出现在 SLua 上，其它任何加载了 Native Plugin 的库都可能出现。

解决办法分两步：第一步是把 Plugins 目录下所有非 WebGL 平台的原生库在 PluginImporter 里取消勾选；第二步是把依赖这些库的初始化逻辑包一层判断，当运行平台是 WebGL 时不加载。如果业务代码不是强依赖，直接移除是最省事的。团队里如果有“必须热更所以我要用 Lua 跑业务”的需求，请重新评估小游戏环境下官方允许的代码热更范围，不然到上线前很被动。

4.3 实例二：No valid Unity Editor license found

这个报错在自动出包机上非常常见，尤其是我把构建脚本放到 CI 上跑的时候。报错内容很直白：Unity 编辑器没有有效的许可证，请激活。

出现这个问题的原因一般有两个：一是这台机器上确实没登录过 Unity 账号，二是许可证过期或因为某种原因从机器上移除了。在 CI 环境里，需要在构建前激活许可，或者把许可证文件放到构建机指定位置。最简单的做法是先在构建机上手动打开一次 Unity Editor，登录并激活许可，确认能正常打开项目后再跑命令行构建。如果维护了多台构建机，那就把许可证的激活过程也写进自动化环境准备流程，避免每次有人换新机才处理一遍。

这里顺带提醒：不要通过任何非官方渠道讨论或使用破解类许可证，这既不符合工具使用规范，也会给后续版本升级挖坑。正规方法激活一次并不复杂，不要因小失大。

4.4 实例三：真机无响应和内存闪烁

京东小游戏在部分 Android 机型上会出现“运行十几秒后无响应”的现象，这往往不是逻辑死循环那么简单。我们遇到的一次，是加载了过多大图素材未释放，导致 WebGL 上下文内存告急。

WebGL 环境对纹理的 GPU 内存占用比较敏感。解决方式有几个：一是把所有美术资源按平台需求做压缩，不要直接扔一张 2048x2048 的 PNG 进去；二是检查场景切换时 AssetBundle 是否正常卸载，避免资源越积越多；三是在 Unity 编辑器里用 Memory Profiler 观察纹理和托管堆的增长曲线，找到泄漏点。

如果游戏本身确实需要很高的内存，可以适当调高 WebGL Memory Size，但要记住这会增加低端机的加载压力。一个平衡做法是：启动时设置一个保守的初始内存，后续根据实际进程状况动态触发扩容，前提是你的宿主环境允许。

4.5 实例四：关系链和排行榜的开放数据域隔离

我们的游戏有好友排行榜，一开始想做得很重，把整张好友列表直接塞进主逻辑。结果京东侧对关系链数据的保护很严格，要求用到关系链数据的模块必须放在开放数据域里，画布也不能直接操作主域场景，只能渲染独立排行榜 Canvas。

这句话翻译一下就是：你不能在主域里拿到用户好友的头像昵称，更不能在主域里肆意读取和传播关系链信息。你需要在开放数据域中请求关系链数据，自己绘制排行榜 UI，把绘制结果传回主域显示。涉及好友关系链、排行榜的功能，建议尽早按平台的“开放数据域”机制实现，否则后期改造比较麻烦，这也是很多非微信平台开发者一开始最容易想当然的部分。

5. 上线后还能继续优化的几个方向

5.1 让首屏加载时间更短

京东小游戏通常有一个体验要求：用户从点击到进入可操作状态的时间越短越好。首屏时间主要由代码包大小、wasm 编译时间、资源加载时间三部分组成。

代码包体积通过裁剪引擎和压缩可以控制，wasm 编译时间在部分低端机上没办法完全消除，但可以通过更早展示加载进度来缓解用户焦虑。真正可控的是资源加载链路。不要把所有图集和音频都放在初始化阶段加载，改造到按关卡、按界面动态加载之后，首屏通常能明显缩短。

另一个做法是延迟初始化不需要立即启动的 SDK。像数据统计 SDK 可以等进游戏主界面后再初始化，不要全部堆在启动时同步调用，否则多个网络请求会让启动链路显得格外漫长。

5.2 从包体分析到资源加载策略

上线一段时间后，如果发现包体快速膨胀，建议每个人都学会使用 Unity 的 Build Report 去分析产物构成。Assets、Shader、AB 包分别占了多少、哪些美术资源重复引用了，这些信息能直接指导资源清理。

纹理压缩在小游戏里非常重要。很多美术资源在原始工程里可能用的是 RGBA32 未压缩格式，在原生平台可以接受，到 WebGL 小游戏里会成倍放大包体积。用 Unity 的 Texture Compression Override 按平台配置一下，通常能在肉眼几乎无差别的情况下省出 30% 以上的体积。

至于资源加载链路，我的习惯是“主线优先、场景并行”。进入战斗前把战斗必要的 AB 包置为最高优先级，次要的 UI 资源等战斗场景加载完再慢慢补。不要用一把梭的同步加载方式，否则切场景时的卡顿和低端机内存峰值迟早会变成线上事故。

5.3 用 Unity Profiler 做小游戏性能定位的替代方案

Unity 的 Profiler 在 WebGL 小游戏上没有原生平台那么好用，尤其真机环境，很难直接连回编辑器。但可以通过几条路来间接定位：一是先在编辑器里把游戏逻辑、GC 分配、场景切换的耗时问题清一遍；二是通过 vConsole 看 JS 层的报错和网络耗时；三是通过内存日志看 Canvas、WebGL 和脚本堆的变化趋势。

最有效的手段还是在代码里埋点。我在关键场景加载、关卡开始、暂停返回等节点打印耗时日志，把小游戏正式包接上远程日志系统。线上用户出现卡死或闪退时，至少能还原出是在哪一步出的问题。靠人肉复现一次两次可以，长期维护没有日志体系一定会很痛苦。

做一个从 Unity 到京东小游戏的完整发布，整体上需要的不是某种高深技巧，而是对整个链路有一颗敬畏心。我最大的体会是：Unity 编辑器里能跑通，不代表宿主真机里能跑通；微信小游戏能跑通，也不代表京东小游戏能跑通。每一次切换平台，都要把适配层、包体限制、域名白名单、开放数据域和真机网络这些“老