微信小游戏 Unity Profiler 性能调优实战指南（minigame-unity-webgl-transform 适配器文档解读）

• 游戏开发
• 移动开发
• WebAssembly

本篇技术指南以当前仓库 Design/Profile.md 为核心，系统讲解如何借助 Unity 官方 Profiler 对导出为微信小游戏的 WebGL 工程进行远程性能采集与调优。文章覆盖从导出勾选、Profiler 窗口监听、微信开发者工具联调到真机调试与端口调整的完整链路，读者读完后可在 Unity 编辑器内实时查看小游戏运行时的 CPU、渲染、内存等关键指标，并掌握连接失败时的手工排查与修复手段。

为什么微信小游戏能用 Unity Profiler

微信小游戏是基于 WebGL/WASM 运行环境的，Unity 官方 Profiler 默认通过本机 TCP 端口与运行中的游戏进程通信。为了跨越浏览器环境，Unity WebGL 播放引擎内置了websockify.js，它负责把 TCP 链路转成 WebSocket 链路，从而让浏览器里运行的小游戏能够把性能数据实时回传给编辑器内的 Profiler 窗口。

整套链路的关键端口与转发关系如下（依据 Design/Profile.md 与 Design/UnityProfiler.md 整理）：

• 34999：Unity 编辑器启动 Profiler 后自监听的调试端口；
• websockify.js：Unity 为 WebGL 版本提供的 WebSocket 转发器，将外部 WebSocket 请求转发到本机localhost:34999；
• 54998：WebGL 构建产物中默认使用的 WebSocket 目标端口（见下文真机调试章节的代码片段）。

导出的 WebGL 游戏（或微信小游戏）运行时自动以ws://ip:port连接 Profiler，数据即可回流到编辑器。这也是本仓库 Design/OptimizationPerformence.md 中描述的"Unity Profiler 在 Editor 监听固定端口、WebGL 游戏以 WebSocket 连接并定期发送性能数据"的运行原理。

第一步：导出时勾选 Development Build 与 Autoconnect Profiler

在 Unity 导出 WebGL 之前，需在Build Settings中开启两个调试选项：

1. Development Build：开启开发构建，保留调试与 Profiler 相关符号；
2. Autoconnect Profiler：让构建产物启动后自动回连 Unity Profiler。

这两项勾选后，使用转换脚本（参考 Design/Transform.md 中关于转换流程与小游戏包结构的说明）导出的 WebGL 资源，在浏览器或微信小游戏环境中运行时就会自动尝试连接 Profiler。

脚本化构建中的对应配置项

如果你希望把这一步集成进自动化构建流程，仓库的配置体系中也提供了同名开关。在 Design/Transform.md 的MiniGameConfig.asset配置说明中：

• DevelopBuild：对应Development Build；
• AutoProfile：对应Autoconnect Profiler。

而在 Design/AssetDescription.md 的CompileOptions配置表中，两者的字段定义如下：

也就是说，无论通过导出面板手动勾选，还是通过修改Assets/WX-WASM-SDK/Editor/MiniGameConfig.asset后调用WXEditorWindow.DoExport()方式脚本导出（见 Design/Transform.md），最终落到构建产物上的效果是一致的。

第二步：打开 Profiler 窗口，建立本地监听

在 Unity 菜单栏执行Window -> Analysis -> Profiler打开 Profiler 窗口。

打开后，Unity 会自动在本机启动对端口34999的监听等待调试连接；对于 WebGL 版本，还会同时拉起websockify.js用于 WebSocket 转发。此时再运行导出的 WebGL 游戏（例如通过Build Settings -> Build And Run打开浏览器运行），游戏就能自动连接到 Unity Profiler，开始回传性能数据。

有一点值得注意：常规流程下，使用 "Build And Run" 打开浏览器时 Unity Profiler 会默认启动监听；如果手动打开了 Profiler 窗口但没有处于监听状态，则需参考后文"重启监听"的方式手工拉起。

第三步：在微信开发者工具中对小游戏进行 Profile

使用转换脚本导出微信小游戏包并启动小游戏后，小游戏会自动连接到 Unity Profiler，随后即可在 Profiler 窗口中实时观测小游戏在微信容器环境下的运行表现。

从截图可以看到，微信开发者工具右侧可以直接内嵌 Unity Profiler 面板，并显示为Autoconnected Player状态，即已成功连接运行在小游戏环境中的游戏实例。这一步无需额外配置，前提是完成第一步的两个勾选项，并确保编辑器内的 Profiler 已处于监听状态。

第四步：真机调试与 IP/端口手工调整

真机自动连接与 vConsole 排查

在 Android 或 iOS 真机上启动小游戏后，游戏会使用ws://ip:port自动连接"Unity Profiler"。这里的 IP 默认是导出（编译）机器的地址。如果无法连接，请优先关注微信开发者工具中vConsole输出的 IP:Port 是否可达，确认真机与编译机器处于同一网络且端口未被防火墙拦截。

修改 IP/端口

如需手工调整 IP 与端口，可修改 WebGL 构建产物中的webgl.wasm.framework.unityweb.js，找到 Profiler 连接地址的赋值逻辑，例如默认代码如下：

if(port == 54998) { url = "ws://127.0.0.1:54998" } ws = new WebSocketConstructor(url, opts); ws.binaryType = "arraybuffer";

将ws://127.0.0.1:54998中的 IP 改为编译机器在局域网内的可达地址（或按需修改端口），即可让真机回连到编辑器的 Profiler。

重启 websockify 监听

一般来说，建议保持端口为54998。若修改了端口，需要重启websockify.js使新端口生效，可在命令行中调用 Unity 自带的 Node 运行转发脚本：

• Windows："$UNITY_PATH/Editor/Data/Tools/nodejs/node.exe" "$UNITY_PATH/Editor/Data/PlaybackEngines/WebGLSupport/BuildTools/websockify/websockify.js" 0.0.0.0:port localhost:34999

• macOS：/Applications/Unity/Hub/Editor/$Verson/Unity.app/Contents/Tools/nodejs/bin/node /Applications/Unity/Hub/Editor/$Verson/PlaybackEngines/WebGLSupport/BuildTools/websockify/websockify.js 0.0.0.0:port localhost:34999 -vv

其中$UNITY_PATH为对应 Unity 版本的安装目录，$Verson为对应的 Unity 版本号，port为对外提供 WebSocket 服务的端口。命令的作用是把外部 WebSocket 请求转发到本机localhost:34999，即编辑器 Profiler 的实际监听端口。macOS 末尾追加-vv可输出更详细的转发日志，便于排查链路问题。参考 Design/UnityProfiler.md 可知，macOS 下 Node 的实际路径为PlaybackEngines/WebGLSupport/BuildTools/Emscripten/node/node，如路径不同请以本机 Unity 安装结构为准。

注意事项与常见问题排查

结合 Design/UnityProfiler.md 与 Design/Profile.md，使用过程中需关注以下几点：

• Profiler 版本稳定性：并非每个 Unity 版本的 Profiler 都足够稳定，如果发现无法正常采集数据，可尝试更换 Unity 小版本；
• 推荐使用 InstantGame 引擎：Unity 2021 建议使用 InstantGame 版本，它支持增强的 Profiler 数据（如更完整的运行时性能与内存分析能力）。仓库 Design/UnityVersion.md 亦说明 2021 InstantGame 增强了 Unity Profiler 内存分析能力；Design/OptimizationMemory.md 也推荐在排查内存问题时使用 InstantGame 的增强 Profiler；
• 连接失败三步排查：当小游戏无法连接 Profiler 时，依次检查——
  1. Unity Profiler 是否已启动监听（未启动时参考上文"重启 websockify 监听"手工拉起）；
  2. IP/端口是否可达（真机场景结合 vConsole 输出确认，桌面端可在微信开发者工具 Network 页签查看对应的 ws 链接是否正常可达）；
  3. 是否已完成第一步的Development Build与Autoconnect Profiler勾选；
• 内存口径认知：Profiler 中看到的内存仅为"引擎可监控内存"，不包含小游戏公共库、Canvas、WebAssembly 编译产物以及容器自身占用的内存，解读数据时需结合 Design/OptimizationMemory.md 的说明综合判断。

与仓库其他性能工具的搭配使用

Unity Profiler 只是本仓库性能优化体系中的一环，建议按场景组合使用：

• 启动与运行热点分析：真机环境下优先使用 使用 Android CPU Profiler 性能调优（勾选 Profiling Funcs 后采集真机 Profile 数据定位热点函数），Unity 环境下则使用本文的 Unity Profiler，二者在 Design/PerfOptimization.md 中被明确推荐为性能分析的配套手段；
• 内存专项分析：当 Native 内存占用偏高时，可配合 使用 ProfilingMemory 分析内存 与 优化 Unity WebGL 内存 进行专项排查；
• 整体调优流程：启动与运行时优化顺序可参考 启动优化 与 运行性能优化 中的完整建议。

附录：Profiler 窗口使用说明

Profiler 窗口各面板（CPU、GPU、Rendering、Memory 等）的具体读数方法与字段释义，可参考 Unity 官方《Profiler 窗口使用说明》文档；若遇到仓库配套相关问题（如导出、配置项含义），可继续查阅 技术常见问题 QA、转换导出说明 以及 资源配置说明 获取更多细节。

• 游戏开发
• 移动开发
• WebAssembly