微信小游戏 Unity 适配：自定义第三方 SDK 调用实战指南（WX.CallJSFunction / SendMessage 双向通信）-平芜编程栈

游戏开发
移动开发
WebAssembly

【免费下载链接】minigame-unity-webgl-transform

微信小游戏Unity引擎适配器文档。

项目地址：https://gitcode.com/GitHub_Trending/mi/minigame-unity-webgl-transform

本文围绕微信小游戏 Unity 适配器提供的自定义 SDK 调用能力展开：通过WX.CallJSFunction/WX.CallJSFunctionWithReturn在 C# 侧直接调用挂载于GameGlobal下的第三方 JS SDK，并通过GameGlobal.Module.SendMessage让 JS 反向调用 C# 方法，实现 Unity 游戏与微信小游戏宿主环境之间的双向数据交互。读完本文你将掌握自定义 SDK 的接入前置条件、参数与返回值约定、双向调用示例，以及如何借助构建模板能力把第三方 SDK 的 JS 代码可靠地打入小游戏产物。

概述：为什么需要自定义 SDK 调用

微信小游戏本质上是一个运行在微信容器中的 JavaScript 运行时环境，Unity 项目经转换插件导出后，游戏逻辑（WASM）与宿主环境之间通过WeChatWASM.WX封装的一套官方 API 通信。但官方 API 无法覆盖所有第三方能力（例如特定统计、登录、风控或渠道 SDK），此时就需要一种通用的“透传”机制，让游戏逻辑能够直接调用任意挂载在全局对象上的第三方 JS 方法，也让第三方 JS 方法能够反向把数据回传给 C# 侧。

微信小游戏 Unity 适配器为此提供了两个层面的接口：

CS 调用 JS：WX.CallJSFunction与WX.CallJSFunctionWithReturn，支持可序列化为 JSON 的任意数量参数与返回值；
JS 调用 CS：通过GameGlobal.Module.SendMessage(objectName, methodName, value)触发场景对象上挂载脚本的方法。

这两个接口组合起来，即可覆盖绝大多数“游戏接入第三方 SDK”的双向通信需求，且无需为每个第三方 SDK 单独编写jslib桥接代码。

版本要求

使用自定义 SDK 调用能力需要转换插件版本 >= 202406062127。如果你的工程内 WX-WASM-SDK-V2 插件版本低于该版本，请先升级转换插件（本仓库各 Demo 工程中的Assets/WX-WASM-SDK-V2即为随版本发布的插件资源目录，可对照升级）。

一、CS 调用 JS：WX.CallJSFunction 与 WX.CallJSFunctionWithReturn

1.1 底层调用规则

WX.CallJSFunction与WX.CallJSFunctionWithReturn是微信 SDK 提供的轻量级“透传”接口。其 JS 侧的实际调用逻辑等价于：

GameGlobal.sdkName.functionName(args)

因此在调用之前必须保证两点：

第三方 SDK 已经挂载在GameGlobal下（例如GameGlobal["sdk"] = sdk;）；
该 SDK 对象中含有对应名称的 function。

两个接口都支持可序列化为 JSON 的任意数量参数，例如嵌套对象、数组、字符串、数字、布尔值等。区别在于返回值处理：

WX.CallJSFunction：只负责调用，不约定返回值处理；
WX.CallJSFunctionWithReturn：会将 JS 函数的返回值转换为 JSON 字符串后传回 C# 侧；若被调函数无返回值，则传回空字符串""。

从仓库 Demo/API_V2/Assets/API 的众多示例（如 Cloud/CallFunction/CallFunction.cs）可以看出，SDK 中所有能力均统一收敛在WeChatWASM命名空间的静态类WX上，回调、参数对象、错误处理等遵循一致的 C# 风格。自定义 SDK 调用的两个接口同样位于该类之下，接入方式与既有 API 完全一致。

1.2 CS 调用 JS 完整示例

下面的示例中，"sdk"、"testFunction"、TestFunctionOption仅作为演示命名，实际使用中请替换为你自己的 SDK 名称、函数名与参数类型。

WeChatWASM.WX.CallJSFunction("sdk", "testFunction", new TestFunctionOption { type = "text", text = "反馈", style = new OptionStyle() { left = 10, top = 10, width = 100, height = 100, backgroundColor = "#ff0000", color = "#ffffff", textAlign = "center", fontSize = 20, borderRadius = 10, lineHeight = 100, } });

其中：

第一个参数"sdk"对应GameGlobal下挂载的 SDK 对象名；
第二个参数"testFunction"对应 SDK 对象内需要调用的函数名；
第三个及后续参数为该函数的入参对象，会以 JSON 形式序列化并透传给 JS 侧。

在 JS 侧代码的合适位置添加以下代码，即可完成 SDK 的全局挂载：

GameGlobal["sdk"] = sdk;

1.3 与构建模板能力配合：把 SDK 代码可靠打入产物

微信小游戏代码包最终由minigame目录构成，若直接手工修改导出产物，修改内容无法跟随代码托管且易被后续导出覆盖。官方推荐的做法是使用构建模板能力：开发者手动创建Assets/WX-WASM-SDK-V2/Editor/template/minigame目录，该目录中的资源会按完整层级结构覆盖到最终导出的minigame目录（详见配置构建模板）。

将上述GameGlobal["sdk"] = sdk;以及第三方 SDK 的 JS 实现放入模板目录（例如.../Editor/template/minigame/third-sdk.js，并在模板的game.js等入口文件中引入执行），即可实现：

自定义 SDK 代码随工程一起版本托管；
每次导出自动合并进小游戏产物，无需手工重复修改；
借助模板的 JSON 配置合并能力，还可直接覆盖game.json、project.config.json中与 SDK 相关的字段（如插件版本号、分包配置等）。

注意：自定义模板中的脚本应以 WXSDK 的基础模板Assets/WX-WASM-SDK-V2/Runtime/wechat-default为修改基准（该目录在 Demo/API_V2/Assets/WX-WASM-SDK-V2/Runtime/wechat-default 可见），而不是以导出产物为参考；基础模板中包含大量占位符，会在导出时按项目实际情况替换。若覆盖了基础模板中的关键.js/.json文件，新版本 WXSDK 导入或导出时会给出冲突警告，需要对比后自行适配。

二、JS 调用 CS：GameGlobal.Module.SendMessage

当第三方 JS SDK 需要把结果回调给游戏（例如登录票据、广告回调、按钮点击事件）时，可以在 JS 侧通过 Unity WebGL 运行时的SendMessage机制反向调用 C# 方法。

// 其中，objectName 是场景中的对象名称；methodName 是当前附加到该对象的脚本中的方法名称；value 可以是字符串、数字，也可为空。 GameGlobal.Module.SendMessage(objectName, methodName, value)

参数约定：

参数	含义	说明
`objectName`	场景中的 GameObject 名称	必须与 Hierarchy 中的对象名完全一致
`methodName`	附加到该对象上的脚本中的方法名	方法需为`public`且参数类型匹配
`value`	传给 C# 方法的参数	可以是字符串、数字，也可以为空

objectName对象下的脚本中需要实现对应的方法：

public void methodName(string value) { // 函数内容 }

实际使用中，建议把 SDK 回调统一收敛到一个常驻的 GameObject 上（例如单例管理器），避免因场景切换导致对象被销毁而丢失回调。在仓库的 API 示例工程中可以看到类似模式——各 API 脚本通过GameManager.Instance等全局入口统一注册回调（参考 Demo/API_V2/Assets/API/Cloud/CallFunction/CallFunction.cs 中对GameManager.Instance.detailsController的使用），这种"单例 + 显式方法"的组织方式同样适用于 JS 侧回调的目标对象。

三、更复杂的调用：结合 jslib 自定义定制

WX.CallJSFunction系列接口覆盖的是"简单函数透传"场景。如果第三方 SDK 需要更复杂的交互（例如需要处理二进制数据、绑定原生事件监听、管理长连接等），官方文档建议参考 Unity WebGL 平台的「与浏览器脚本交互」方案进行自定义定制。

Unity WebGL 支持通过.jslib文件把 C# 侧的方法桥接到浏览器 JavaScript。在仓库的 Demo/API_V2/Assets/Plugins 目录下可以看到实际的jslib使用样例，例如：

TransparentBackground.jslib：演示如何通过jslib调用浏览器/小游戏宿主侧的底层能力；
WebGL/WebSocket.jslib：演示在.jslib中封装较复杂的事件式 API（如 WebSocket 的连接、消息、关闭回调），为“简单透传不适用”的场景提供了扩展路径。

在jslib中同样可以直接访问GameGlobal（微信小游戏宿主中GameGlobal即全局对象），因此两种方案可以混用：

简单调用 →WX.CallJSFunction/WX.CallJSFunctionWithReturn，零额外代码；
复杂交互（事件订阅、二进制、长连接）→jslib自定义封装，获得完整控制权。

四、实战注意事项

挂载时机：GameGlobal["sdk"] = sdk;必须在调用WX.CallJSFunction之前完成，否则 JS 侧会因找不到对象或函数而报错。建议把 SDK 初始化脚本放在构建模板的入口逻辑中、引擎启动之前执行。
JSON 序列化边界：参数与返回值只支持可序列化为 JSON 的数据。二进制数据、函数引用等无法直接透传，此类场景请走jslib定制方案。
无返回值约定：使用WX.CallJSFunctionWithReturn时，若 JS 函数没有返回值，C# 侧收到的是空字符串""，注意判空处理。
命名冲突：挂载到GameGlobal的 SDK 名称应保持唯一且有辨识度，避免覆盖小游戏宿主已有的全局对象（如GameGlobal.Module、GameGlobal.wx等）。
版本门槛：确认转换插件版本不低于202406062127，否则相关接口可能不可用。
代码托管：所有自定义 JS 代码应放入构建模板目录随工程托管，并关注 WXSDK 更新时对基础模板覆盖文件的冲突警告（详见配置构建模板）。

小结

自定义 SDK 调用是微信小游戏 Unity 工程接入第三方能力的通用通道：WX.CallJSFunction/WX.CallJSFunctionWithReturn打通了 C# → JS 的透传链路（以GameGlobal.sdkName.functionName(args)为最终执行形态），GameGlobal.Module.SendMessage打通了 JS → C# 的回调链路，配合构建模板能力可将 SDK 代码稳定、可托管地合入小游戏产物；对于超出简单透传范围的复杂交互，则可借助jslib（仓库 Demo/API_V2/Assets/Plugins 提供了现成样例）进行完全自定义的桥接实现。