Unity WebGL 编译和打包说明（官方文档翻译校正）

目录

• Unity WebGL 编译和打包说明
• WebGL 简介
• • WebGL 浏览器兼容性 (WebGL Browser Compatibility)
  • • 平台支持 (Platform Support)
    • 多线程支持
    • • 限制多线程支持的因素
      • 安装 Unity Hub 并添加所需模块
• WebGL 开发
• • WebGL Player 设置
  • • Resolution and Presentation
    • • Resolution
      • WebGL Template
    • Splash Image
    • Other Settings
    • • Rendering
    • Configuration
    • Shader Variant Loading
    • API Compatibility Level
    • Script Compilation
    • Optimization
    • Stack Trace
    • Legacy
    • Publishing Settings
    • • Show Diagnostic Overlay 设置
      • Important note about JS Memory
  • 与浏览器脚本的交互
  • • 代码示例：在 Unity 中调用 JavaScript 和 C/C++/C# 函数
    • • 在 Unity C# 示例中调用 JavaScript 代码
      • 在 Unity C# 脚本中调用 C/C++/C# 代码示例
    • 设置 JavaScript Plug-in
    • • 将你的 JavaScript 文件导入到 Unity 项目中
      • 从 .jslib 文件类型中调用函数
      • 使用 .jspre 文件类型包含 JavaScript 库
    • 从 Unity C# 脚本调用 JavaScript 函数
    • • 传递不同的变量从 JavaScript 到 Unity
      • • 数值类型
        • 字符串
        • 数组
        • 纹理
      • 在自己的作用域中执行构建代码
      • • .jslib 插件中的代码
        • 从全局作用域（Global Scope）调用 JavaScript 函数
      • 调用 JavaScript 函数的示例 Unity C# 代码
      • 使用 Unity 插件作为参考
    • 从 JavaScript 调用 Unity C# 脚本函数
    • • 使用 SendMessage 辅助函数
      • SendMessage 代码示例
    • 从 Unity C# 脚本调用 C/C++/C# 函数
    • • 将你的 C/C++/C# 插件导入 Unity 项目
      • 在 Unity 中使用的 C++ 代码示例
    • 将静态库编译为 Unity 插件
    • • 在 Unity 中使用静态库的步骤
      • • 下载 Emscripten SDK
        • 配置现有项目脚本
        • 更新编译器选项
        • 编译并导入静态库文件
        • 从 Unity C# 脚本调用静态库函数
    • 在 Unity C#、JavaScript 和 C/C++/C# 代码之间创建回调
    • • 使用 `makeDynCall` 函数进行回调
      • 在脚本中使用回调
      • • JavaScript 插件代码
      • C++ 插件代码
      • Unity C# 代码
  • WebGL 原生插件与 Emscripten
  • • 目标版本
    • • 说明：
    • 使用 Emscripten 编译原生插件
    • • 注意：
      • Emscripten 构建标志
  • Unity WebGL 中的内存
  • • Unity WebGL 中的内存约束
    • Unity Heap
    • 资源数据（Asset data）
    • 垃圾回收
  • WebGL 中的缓存行为
  • • 数据缓存
    • 自定义 WebGL 缓存行为
  • WebGL 图形
  • • 相机清除（Camera clear）
    • 延迟渲染
    • 全局照明
    • 线性渲染（Linear rendering）
    • 视频剪辑导入器（Video clip importer）
    • WebGL 着色器代码限制
    • 字体渲染
    • 抗锯齿（Anti-aliasing）
    • 反射探针（[Relection Probe](https://docs.unity3d.com/2022.3/Documentation/Manual/class-ReflectionProbe.html)）
    • WebGL 2.0 支持
  • WebGL 中的音频
  • • 支持的类
    • AudioSource
    • AudioClip
    • 压缩音频
    • 音频播放和浏览器安全
  • WebGL 中的纹理压缩
  • • 纹理压缩格式
    • 压缩格式设置的优先级
    • 设置默认压缩格式
    • 通过脚本为桌面和移动浏览器创建构建
  • WebGL 中的嵌入式资源 (Embedded resources in WebGL)
  • • WebGL 中的嵌入式资源 (Embedded resources in WebGL)
  • WebGL 中的输入
  • • 游戏手柄和操纵杆支持
    • • 控制器映射
    • 触摸支持
    • 键盘输入和焦点处理
    • 移动传感器支持
    • 光标锁定支持
    • • 启用光标锁定
      • 取消光标锁定
      • 粘性光标锁定
      • 全屏模式
      • 在 Web 中启用全屏模式
      • 退出全屏模式
    • 全屏模式和光标锁定的附加注意事项
  • 配置 WebGL 画布大小
  • • 画布大小元素
    • 解耦渲染分辨率
    • • 覆盖 DPI 缩放
    • 手动更改 WebGL 画布渲染大小
  • WebGL 浏览器访问设备功能
  • WebGL Networking
  • • 在 WebGL 中使用 UnityWebRequest 类
    • • UnityWebRequest 下载
    • 使用 Unity Multiplayer
    • 从 JavaScript 使用 WebSockets 或 WebRTC
    • WebGL 网络的限制
    • • 不支持 native socket access
  • WebGL 性能考虑
  • • 影响性能的 WebGL 特定设置
    • WebGL 性能分析
    • 后台标签中的 WebGL 内容
    • 节流 WebGL 性能
  • 调试和排除 WebGL 构建问题
  • • 浏览器中的 JavaScript 控制台
    • 开发构建（Development builds）
    • 异常支持
    • 故障排除
• 构建（Build）和分发（Distribute） WebGL 应用程序
• • WebGL 构建设置
  • • 访问 WebGL 的构建设置
    • • WebGL 构建设置参考
  • 构建 WebGL 应用程序
  • • 构建文件夹结构
    • 启用异常
    • 优化你的 WebGL 构建
    • • 优化 WebGL 构建的推荐图形设置
      • • 设置推荐值及描述
        • Lightmap Modes
        • Fog Modes
        • Instancing Variants
        • Batch Renderer Group Variants
        • Always Included Shaders
        • 通过脚本编辑 Always Included Shaders 列表
      • 推荐的 Player 设置以优化 WebGL 构建
      • • Player 设置快速参考
        • API Compatibility Level
        • IL2CPP Code Generation
        • Managed Stripping Level
        • Compression Format
        • Data Caching
        • Debug Symbols
        • Enable Exceptions
      • 推荐的质量设置以优化 WebGL 构建
      • • 质量级别
        • 通过 C# 代码更改质量级别
      • 使用 C# 代码启用优化设置
      • • 创建一个 C# 脚本来优化您的 WebGL 构建
    • 优化 WebGL 平台以适应移动设备
    • • 优化快速参考
      • 优化尺寸
      • • 使用 C# 启用优化尺寸设置
      • 使用 Brotli 压缩
      • • 使用 C# 更改压缩格式
      • 使用 Unity Addressables 系统
      • 优化音频文件
      • 优化项目中的图形
      • 启用 Shader 剥离
      • 降低图形质量等级
    • 使用 AssetBundles 减少加载时间
    • WebGL 的发布大小和代码剥离
    • • 针对 WebGL 的提示和技巧
      • 代码剥离
      • • 代码剥离的问题
      • 移动构建输出文件
      • 增量构建
  • WebGL Template
  • • 添加 WebGL 模板
    • 模板变量、宏和条件指令（Template variables, macros, and conditional directives）
    • • 内部预处理变量（Internal preprocessor variables）
    • JavaScript Macros
    • 条件指令（Conditional directives）
    • • 自定义用户变量（Custom user variables）
    • index.html 文件的结构
    • • 实例化函数：createUnityInstance()
    • 构建配置
    • 构建交互（Build interaction）
  • 部署 WebGL 应用程序
  • • 压缩格式
    • Web 服务器配置
    • 解压回退（Decompression fallback）
    • • 启用解压回退
      • 禁用解压回退
    • Content-Encoding 头
    • WebAssembly streaming (higher level header)
    • 其他头
  • 服务器配置代码示例
  • • Nginx 服务器配置（WebGL 构建）
    • Apache 服务器配置（WebGL 构建）
    • IIS 服务器配置（压缩的 WebGL 构建，不带解压回退）
    • IIS 服务器配置（未压缩的 WebGL 构建）
• 参考

Unity WebGL 编译和打包说明

Unity 提供了对 WebGL 平台开发游戏的支持。WebGL 允许开发者将实时交互的3D图形发布到浏览器中。

WebGL 简介

Unity 编辑器中的 WebGL 选项允许您将内容发布为 JavaScript 程序，这些程序使用 HTML5/JavaScript、WebAssembly、WebGL rendering API 以及其他 Web 标准在 Web 浏览器中运行 Unity 内容。

WebGL 浏览器兼容性 (WebGL Browser Compatibility)

Unity 对桌面浏览器的 WebGL 支持因浏览器而异，支持满足以下条件的浏览器：

• 支持 WebGL 2：注意，Unity 不再为使用 Auto Graphics API 选项创建的构建提供 WebGL 1 的支持。更多详情，请参见 WebGL 1 的弃用。
• 符合 HTML 5 标准：浏览器应符合 HTML 5 标准。
• 64 位并支持 WebAssembly：浏览器应为 64 位并支持 WebAssembly。

Unity WebGL 不支持移动设备。尽管可能在高端设备上运行，但当前的移动设备通常性能不足且内存不够，无法支持 Unity WebGL 内容。

Unity WebGL 支持一些压缩纹理格式。有关 Unity WebGL 支持的压缩纹理格式的信息，请参见 Recommended, default, and supported texture compression formats, by platform 。

平台支持 (Platform Support)

大多数流行的桌面浏览器版本都支持 Unity WebGL 内容，但请注意，不同的浏览器提供的支持水平不同。例如，Unity WebGL 不支持移动设备。

由于平台本身的限制，WebGL 构建中的以下功能不可用或有限：

• Visual Studio 中缺乏 WebGL 构建调试支持Visual Studio 不支持调试 Unity WebGL 构建。更多信息，请参见 Debug and troubleshoot WebGL builds 。
• 缺乏 Unity 缓存和缓存脚本支持由于浏览器对文件系统的访问受限，WebGL 构建不支持 Unity Cache 和 Caching Scripting API。对资产数据（asset data）和 AssetBundles 的网络请求会被缓存到浏览器缓存中。请参阅 Cache behavior in WebGL 。
• 缺乏线程支持由于 JavaScript 不支持线程，因此不支持线程。这适用于 Unity 内部使用线程来加速性能的情况，以及在脚本代码和 managed DLL 中使用线程的情况。本质上，System.Threading 命名空间中的任何内容都不支持。
• 网络限制WebGL 平台不支持以下几项网络功能：
  • 出于安全考虑，浏览器不允许直接访问 IP sockets 。更多信息，请参见 Web networking 。
  • System.Net 命名空间中的 .NET networking class 不受支持。
  • 由于浏览器的安全限制，WebGL 平台不支持 native socket 访问。因此，WebGL 也不支持 ICMP ping 或 UnityEngine.Ping 等功能。
• 图形限制WebGL 平台的图形 API 基于 OpenGL ES 图形库的功能，有一些限制。更多信息，请参见 WebGL graphics 。
• 音频限制WebGL 构建使用基于 WebGL Audio API 的自定义音频后端，但它只支持基本的音频功能。更多信息，请参见 Audio in WebGL 。
• 代码的动态生成WebGL 是一个 AOT（Ahead Of Time）平台，因此不允许使用 System.Reflection.Emit动态生成代码。所有其他 IL2CPP 平台、iOS 和大多数游戏主机也是如此。
• 复制和粘贴复制和粘贴功能仅在 Unity UI 内部有效。无法从系统剪贴板（system clipboard）复制和粘贴，也就是说，无法与外部应用进行复制或粘贴操作。

多线程支持

尽管 Unity 为 native C/C++ 代码提供了多线程支持，但由于 WebAssembly 的限制，Web 平台尚不支持 C# 多线程。这意味着使用 Web 平台构建的应用必须在单个 C# 线程上运行。

• Web 平台仅在启用 Web Player settings中的 Native C/C++ support 支持时支持 C/C++ 多线程。
• 当document处于安全上下文中时，Web 平台支持多线程。
• 服务器必须设置以下 HTTP 响应头：
  • Cross-Origin-Opener-Policy: same-origin
  • Cross-Origin-Embedder-Policy: require-corp
  • Cross-Origin-Resource-Policy: cross-origin
• 在 Web 平台上执行复杂的异步任务的推荐方法是使用协程（不是多线程操作）。更多信息，请参见 coroutines 文档。

限制多线程支持的因素

• 本地堆栈扫描（native stack scanning）的限制Web 平台使用 WebAssembly，这是一种用于在 Web 浏览器中安全高效地执行 Unity 代码的字节码格式。Web 浏览器设计为在安全和隔离的环境中运行代码，阻止直接访问本地 WebAssembly 堆栈。这影响了多线程垃圾回收，因为 Web 的垃圾回收器仅在每帧结束时运行一次，而不像其他平台那样在多帧之间增量运行。
• 没有抢占式线程信号（pre-emptive thread signaling）支持Web 上的后台工作线程独立并行执行代码。在 native 平台上，主线程可以同步发送信号给其他线程暂停以进行垃圾回收。Web 上不支持这种同步信号，这阻止了 WebAssembly 编译的 C# 代码在多个线程上运行。
• 其他资源 (Additional Resources)
  • Secure context
  • Garbage collection

安装 Unity Hub 并添加所需模块

要构建 WebGL 应用程序，首先必须安装 Unity Hub，然后添加 WebGL Build Support 模块。

有关如何完成这些步骤的信息，请参阅安装 Unity Hub和向 Unity 编辑器添加模块。

WebGL 开发

WebGL Player 设置

使用 Player 设置了解 Unity 如何构建（build）并显示最终的 WebGL 应用程序。有关一般 Player 设置的说明，请参阅 Player settings。

要访问 WebGL Player 设置：

1. 从 Unity 主菜单中，转到 Edit > Project Settings > Player。Player 设置窗口将出现。
2. 选择 WebGL 选项卡以查看 WebGL Player 设置。

注意：虽然 WebGL Player 设置中显示了图标面板，但没有图标设置可用，因为 WebGL 游戏不使用图标。

有关 WebGL Publishing Settings 的更多信息，请参阅 WebGL Building and Running。

Resolution and Presentation

使用 Resolution and Presentation 部分自定义屏幕外观的各个方面。

Resolution

WebGL Template

选择要用于 WebGL 项目的模板：

• Default 页面是一个简单的白色页面，灰色画布上有加载条。
• Minimal 页面只有运行 WebGL 内容所需的基本代码。
• PWA 页面包括一个 Web manifest 文件和 service worker 代码。您可以指定自己的模板，以便在类似于成品游戏的环境中运行您的游戏。有关详细说明，请参阅 Using WebGL Templates 。

Splash Image

使用虚拟现实启动画面设置为 XR 显示器选择自定义启动图像。有关常见启动屏幕设置的信息，请参阅 Splash Screen 。

Other Settings

Rendering

使用这些设置可以自定义 Unity 如何为 WebGL 平台渲染您的游戏。

Configuration

Shader Variant Loading

使用这些设置控制运行时着色器使用的内存量。

API Compatibility Level

您可以为所有 target 选择 Mono API 兼容性级别。有时，第三方 .NET 库使用的功能超出了您的 .NET 兼容性级别。要了解这种情况下的情况以及如何最好地解决它，请尝试以下建议：

1. 为 Windows 安装 ILSpy 。
2. 将导致问题的 API 兼容性级别的 .NET 程序集拖入 ILSpy。您可以在 Frameworks/Mono/lib/mono/YOURSUBSET/ 下找到这些问题文件。
3. 拖入您的第三方程序集。
4. 右键单击第三方程序集并选择 Analyze 。
5. 在分析报告中，检查 Depends on 部分。报告会突出显示第三方程序集依赖但不在您选择的 .NET 兼容性级别中可用的任何内容。

Script Compilation

Optimization

Stack Trace

为 WebGL 平台选择日志记录设置。

选择与每种日志类型（Error、Assert、Warning、Log 和 Exception）对应的选项，以基于所需的日志记录类型启用首选的堆栈跟踪方法。有关更多信息，请参阅 stack trace logging。

Legacy

启用 Clamp BlendShapes（已弃用）选项以在 Skinned Mesh Renderers 中夹住混合形状权重的范围。

Publishing Settings

使用 Publishing Settings 配置 Unity 构建 WebGL 应用程序的方式。例如，您可以选择启用浏览器缓存以在构建中存储其文件。

Show Diagnostic Overlay 设置

为了帮助优化 WebGL 构建并诊断潜在问题，您可以通过启用此设置查看诊断信息（目前限于内存使用情况）。启用后，构建上会出现一个图标，显示有关构建的有用数据。此选项适用于开发和发布构建。

要查看诊断信息，请在 Player settings 窗口（File > Build Settings > Player Settings > Publishing Settings）中启用 Show Diagnostics Overlay 选项。

在桌面上，诊断图标出现在 WebGL 画布的页脚：

在移动设备上，诊断图标出现在屏幕右下角：

点击 Diagnostics 图标。会出现一个覆盖层，显示 JavaScript 内存的详细信息，其中进一步细分显示 WASM 堆内存使用情况：

覆盖屏幕上显示以下诊断信息：

属性 (Property)

功能 (Function)

Total JS Memory

JavaScript（JS）堆的当前大小，包括未分配给任何 JS 对象的未使用内存，以兆字节（MB）为单位。

Used JS Memory

JS 对象使用的内存，以兆字节（MB）为单位。

Total WASM heap memory

表示 C/C++ Unity 引擎使用 Emscripten 编译的整个堆内存的线性内存，包括未分配的内存，以兆字节（MB）为单位。

Used WASM heap

已分配的 WASM 堆空间，以兆字节（MB）为单位。

Important note about JS Memory

JS 内存信息是使用 performance.memory API 获得的，目前仅支持 Chrome 或 Edge。没有其他 API 可返回此信息以供 Safari 或 Firefox 使用。

注意：iOS 设备不支持 performance.memory API。

在不支持此 API 的浏览器上，会显示消息 “N/A”。

与浏览器脚本的交互

当你为 Web 构建内容时，可能需要与网页上的其他元素进行通信，或者使用 Web API 来实现 Unity 默认未提供的功能。

在这两种情况下，你都需要直接与浏览器的 JavaScript 引擎进行交互。Unity Web 提供了不同的方法来处理这些交互。

代码示例：在 Unity 中调用 JavaScript 和 C/C++/C# 函数

你可以使用代码在插件和 Unity 代码之间执行交互。以下示例展示了如何在 Unity 项目中从 JavaScript 和 C/C++/C# 代码调用各种类型的函数。

在 Unity C# 示例中调用 JavaScript 代码

以下代码是一个 JavaScript 示例，你的 Unity C# 脚本可以从中调用函数。

mergeInto(LibraryManager.library, {

  Hello: function () {
    window.alert("Hello, world!");
  },

  HelloString: function (str) {
    window.alert(UTF8ToString(str));
  },

  PrintFloatArray: function (array, size) {
    for(var i = 0; i < size; i++)
        console.log(HEAPF32[(array >> 2) + i]);
  },

  AddNumbers: function (x, y) {
    return x + y;
  },

  StringReturnValueFunction: function () {
    var returnStr = "bla";
    var bufferSize = lengthBytesUTF8(returnStr) + 1;
    var buffer = _malloc(bufferSize);
    stringToUTF8(returnStr, buffer, bufferSize);
    return buffer;
  },

  BindWebGLTexture: function (texture) {
    GLctx.bindTexture(GLctx.TEXTURE_2D, GL.textures[texture]);
  },

});

以下代码是一个 Unity C# 示例，调用了上述 JavaScript 示例中定义的函数。

using UnityEngine;
using System.Runtime.InteropServices;

public class NewBehaviourScript : MonoBehaviour {

    [DllImport("__Internal")]
    private static extern void Hello();

    [DllImport("__Internal")]
    private static extern void Hel