Unity WebGL实战笔记_webgl builds are not supported on mobile devices

笔者版本为：Unity2021.3.8f1
Unity提供了WebGL平台来，支持在浏览器中实时对3D图形应用交互。

设置

模版

Player->Resolution and Presentation->WebGL Template
默认是Default，这个模版有加载进度条，且在程序出错会弹出提示框。还有一个Minimal模版，没有进度条加载等流程，且程序出错无提示信息。
我们也可以自己自定义模版，放到Editor\Data\PlaybackEngines\WebGLSupport\BuildTools\WebGLTemplates目录下即可使用。

压缩

Player->Publishing Settings->Compression Format。可以设置压缩格式，一般的话会设置Gzip压缩。若无法确保服务端是否支持压缩格式，则建议设置为Disabled

代码裁切

Strip Engine Code可以大大降低WebGL文件大小，Unity 会扫描项目中所有从 UnityObject 继承的类型，包括检查它的内部引用以及序列化字段，将会移除没有任何引用的类型，从而减少发布大小，生成的代码也更少、更快、内存占用更少。但是要慎用其裁剪等级，需要多次测试选择合适的等级。官方文档：Managed code stripping。
对于使用了Assetbundle的项目代码裁剪很容易丢失对类的引用。运行时会看到错误Could not produce class with ID XXX,针对这种情况一般可以按如下方式解决：
step1:根据提示 ID，查找裁剪的类型:ClassIDReference
step2:设置不被裁剪
可以在代码中强制引用一下step1中找到的类型，或者在Assets目录下创建link.xml文件，强制引用，格式如下：

<linker>
    <assembly fullname="UnityEngine">
        <type fullname="UnityEngine.Collider" preserve="all"/>
    </assembly>
</liner>
1
2
3
4
5

Strip Engine Code选项只是针对 Unity 的本机代码，对于托管代码来说，总是会进行代码裁剪，IL2CPP 通过托管 DLL，以及代码脚本中的静态引用，来进行代码裁剪，如果代码中使用反射来获取类型，那么同样的，该类型有可能被裁剪掉，因此也需要添加到 linker.xml中。

色彩空间

默认是Gamma模式。若要使用Linear模式，则图形API只能选择WebGL 2.0

WebGL 2.0

WebGL 2.0 于 2017 年首次发布。相比上一版本，WebGL 2.0在图形功能方面实现了很大提升，带来了OpenGL ES 3.0 功能集，为 WebGL 1.0 图形管道添加了对变换反馈、实例渲染、多个渲染目标、统一缓冲区对象、遮挡查询和更广泛的纹理支持的访问。
目前几乎所有主流浏览器都支持WebGL 2.0了(Safari浏览器需要iOS15+才支持WebGL 2.0)。目前笔者使用Unity版本WebGL 1.0旁标示了Deprecated。

抗锯齿

默认情况下WebGL设置的品质比较低，锯齿感比较强，可以在性能允许的前提下通过增加Anti Aliasing级别以及设置Quality的级别来增加显示效果。但是在 WebGL 1.0 中存在一些限制：

• 不能在运行时启用/禁用，必须在系统发布时就确定；
• 多重采样（multi sampleing 2x、4x…)没有作用，只有开启、关闭两个状态；
• 如果 Camera 上又任何Post-Processing-Effect，都会引起抗锯齿失效；
• HDR 和抗锯齿是不兼容的，如果开启抗锯齿，就需要关闭 Camera上的 Allow HDR选项。

WebGL2.0 不存在以上限制。

Enable Exceptions

Player->Publishing Settings/Enable Exceptions提供了异常处理选项

• None 不需要异常支持，性能最好，发布包最小，但是任何错误都会引起系统停止（可以在确认没有bug的情况下再切换到这个设置）；
• Explicitly Thrown Exceptions Only ： 默认设置，能够捕获由代码中 throw 抛出的异常，并且能够正确执行 finally 语句块，这将会引起生成大 JavaScript 代码更长、更慢，但这通常只在代码引起瓶颈时才要考虑；
• Full Without Stacktrace：能够捕捉如下异常：
  • throw 抛出的异常
  • 空引用异常，Null Reference
  • 数组越界
• Full With Stacktrace：和上面比多了一个调用栈信息，通常应该在调试阶段使用，并且在 64 位浏览器中测试。

Compression Format

Player->Publishing Settings/Enable Exceptions提供了导出文件的压缩处理选项，默认为Gzip

• Brotli
  Google 在 2015 年 9 月推出了无损压缩算法 Brotli。Brotli 通过变种的 LZ77 算法、Huffman 编码以及二阶文本建模等方式进行数据压缩，与其他压缩算法相比，它有着更高的压缩效率。
  Brotli 压缩算法具有多个特点，最典型的是以下 3 个：
  针对常见的 Web 资源内容，Brotli 的性能相比 Gzip 提高了 17-25%；
  当 Brotli 压缩级别为 1 时，压缩率比 Gzip 压缩等级为 9（最高）时还要高；
  除了 IE 和 Opera Mini 之外，几乎所有的主流浏览器都已支持 Brotli 算法。
  brotli浏览器支持情况查询.
  Brotli压缩速度慢，且只支持https协议。
• Gzip
  Gzip 基于 DEFLATE 算法，它是 LZ77 和霍夫曼编码的组合，最早用于 UNIX 系统的文件压缩。HTTP 协议上的 Gzip 编码是一种用来进 Web 应用程序性能的技术，Web 服务器和客户端（浏览器）必须共同支持 Gzip，当下主流的浏览器都是支持 Gzip 压缩。
• Disabled
  不压缩，包体会比较大

服务端的配置可以参考如下官方文档：
Compressed builds and server configuration
Server configuration code samples

Data Caching

默认启用，会使用资源缓存到浏览器的 IndexedDB 数据库，在后面运行的时候不用再次从服务器下载资源，不同浏览器的缓存策略也不尽相同。如果只是想进行空引用检查和数组越界检查，而不想完全支持异常，可以通过如下代码来支持：

using UnityEditor;

public class WebGLEditorScript
{
    [MenuItem("WebGL/EnableNullChecks")]
    public static void EnableNullChecks()
    {
        PlayerSettings.SetPropertyString("additionalIl2CppArgs", "--emit-null-checks --enable-array-bounds-check",UnityEditor.BuildTargetGroup.WebGL);
    }
}
1
2
3
4
5
6
7
8
9
10

AssetBundles

WebGL 在启动之前，需要将所有的资源预加载完成，因此减少启动时间的一个有效方式就是减少系统资源，或者说减少发布资源，可以利用 AssetBundle 将资源从主包中分离出来，这样，只需要加载一个非常小的加载场景即可，另外 AssetBundle 还能帮助资源管理。

在 WebGL 平台使用 AssetBundle 有以下几点需要注意：

• AssetBundle 中包括主包中没有的类型时，会引起资源加载失败，最好是在 AssetBundle 中不要打包新类型；
• WebGL 不支持多线程，而AssetBundle 数据在 Http 下载完成后才可用，因此，AssetBundle 就需要在主线程进行解压缩，这会引起主线阻塞，LZMA 在 WebGL 平台是不可用的，因为它是整包压缩，可以采用 LZ4 压缩，它是单个资源独立压缩，即加载单个资源时，不需要解压整个资源包，如果需要更小的资源包格式，可以采用 gzip 或者 brotli 进行二次压缩，不过这需要 web 服务器进行相应的配置；
• 支持 WWW.LoadFromCacheOrDownload 方法，它采用浏览器的 IndexedDB 来实现缓存；

字体

WebGL 支持动态字体，但是由于它不能访问本机文件系统，所以使用到的字体文件必须放到项目当中。（包括 Fallback fonts，以及粗体和斜体字体），另外需要注意的是，默认的Arial字体在浏览器中不支持中文（Arial字体本来就不支持中文，只是在PC或者移动端终端失败后会在设备中寻找合适字体进行替代），需要自行替换字体以支持。

为了提高性能，建议在 WebGL 中使用 TMP 来替代默认的 UGUI 文本组件，使用静态字体来替代动态字体。

发布

项目文件结构

以Default模版为例，目录结构为

• Build
  已翻译为js的源码和相关插件
• StreamingAssets
  项目中的 StreamingAssets 文件夹(WebGL平台下 Application.streamingAssetsPath 的值为 http://youer_host_url:port/StreamingAssets)
• TemplateData
  包含Default模版需要的logo、进度条等UI。Minimal模版下无此文件夹。
• index.html

持久化数据

Unity WebGL将所有持久化数据（PlayerPrefs、缓存）都保存到浏览器的 IndexedDB 中，在开发者工具中，可以通过 Application 标签页查看，这一API 是异步的，所以不知道什么时候能够完成。因此可能会遇到报错：Problem: Files saved to Application.persistentDataPath do not persist

运行index.html

Build Settings页面Build后生成的文件index.html,双击后一般来说是无法顺利运行的。
若选择的模版是Default则会弹出报错提示界面，内容为：

Failed to download file Build/web_output.data.gz. 
Loading web pages via a file:// URL without a web server is not supported by this browser. 
Please use a local development web server to host Unity content, or use the Unity Build and Run option.
1
2
3

若模版是Minimal则无提示信息，界面空白，只能从浏览器Console查看报错日志：

Access to fetch at 'file:///C:/MetaProject/webAvatarShow/web_output/Build/web_output.data.gz' from origin 'null' has been blocked by CORS policy: 
Cross origin requests are only supported for protocol schemes: http, mnt, https, nb, data, chrome, tx, chrome-untrusted, chrome-extension.
1
2

针对这个报错，若不想通过搭建服务器的方式来解决的话，目前有两种处理方式来解决。
1，依旧使用Build，且需要使用Firefox浏览器来查看（Chrome,Edge等其它浏览器都不行），而且Firefox还需要进行如下设置：

在地址栏输入 about:config,出现Firefox配置信息，在Search输入webgl

双击webgl.forece-enabled设置为true;强制开启webgl支持

双击webgl.forece-disabled设置为false (如果没有该项，则忽略)

搜索security.fileuri.strict_origin_policy设置为false;允许从本地加载资源

重启firefox
1
2
3
4
5
6
7
8
9

若是有如下报错，则是因为设置了Gzip压缩格式，可以通过设置压缩格式为Disabled来规避，或者勾选Publishing Settings->Decompression Fallback也可以规避该问题。

Unable to parse Build/web_output.framework.js.gz! Loading pre-compressed (brotli or gzip) content via a file:// URL without a web server is not supported by this browser. 
Please use a local development web server to host compressed Unity content, or use the Unity Build and Run option.
1
2

2，使用Build And Run，unity会自己在本地搭建个服务器，且完美支持Gzip压缩。

nginx发布

若设置了Gzip压缩，则浏览器运行后会报错

Unable to parse Build/web_output.framework.js.gz! 
This can happen if build compression was enabled but web server hosting the content was misconfigured to not serve the file with HTTP Response Header "Content-Encoding: gzip" present. 
Check browser Console and Devtools Network tab to debug.
1
2
3

这是服务端未支持Gzip导致的。可以通过禁用压缩，或者设置Decompression Fallback来规避（实质是在发布包内集成了一个对应压缩方式的js解压工具，在浏览器解压失败会使用该工具进行解压，这样会增加加载的时间）。
若是要求使用压缩且发布包不想集成解压工具，则可以按照官方文档：Server configuration code samples把以下配置添加到conf/nginx.conf中：

# On-disk Brotli-precompressed data files should be served with compression enabled:
location ~ .+\.(data|symbols\.json)\.br$ {
    # Because this file is already pre-compressed on disk, disable the on-demand compression on it.
    # Otherwise nginx would attempt double compression.
    gzip off;
    add_header Content-Encoding br;
    default_type application/octet-stream;
}

# On-disk Brotli-precompressed JavaScript code files:
location ~ .+\.js\.br$ {
    gzip off; # Do not attempt dynamic gzip compression on an already compressed file
    add_header Content-Encoding br;
    default_type application/javascript;
}

# On-disk Brotli-precompressed WebAssembly files:
location ~ .+\.wasm\.br$ {
    gzip off; # Do not attempt dynamic gzip compression on an already compressed file
    add_header Content-Encoding br;
    # Enable streaming WebAssembly compilation by specifying the correct MIME type for
    # Wasm files.
    default_type application/wasm;
}

# On-disk gzip-precompressed data files should be served with compression enabled:
location ~ .+\.(data|symbols\.json)\.gz$ {
    gzip off; # Do not attempt dynamic gzip compression on an already compressed file
    add_header Content-Encoding gzip;
    default_type application/octet-stream;
}

# On-disk gzip-precompressed JavaScript code files:
location ~ .+\.js\.gz$ {
    gzip off; # Do not attempt dynamic gzip compression on an already compressed file
    add_header Content-Encoding gzip;
    default_type application/javascript;
}

# On-disk gzip-precompressed WebAssembly files:
location ~ .+\.wasm\.gz$ {
    gzip off; # Do not attempt dynamic gzip compression on an already compressed file
    add_header Content-Encoding gzip;
    # Enable streaming WebAssembly compilation by specifying the correct MIME type for
    # Wasm files.
    default_type application/wasm;
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47

手机浏览器运行

由于手机性能问题，WebGL默认是不建议使用手机浏览器的，通过Default模版出的包，一开始会弹出提示框WebGL builds are not supported on mobile devices.，当然如果程序没问题，那么依旧是可以继续运行的。
若是想禁用Default模板下的这个提示框，可以在index.html中注释unityShowBanner('WebGL builds are not supported on mobile devices.');即可。
但是笔者在iOS手机safari浏览器运行后弹出了报错窗口（需要使用Default模版才会有报错窗口，Minimal模版无报错窗口，因此为了调试方便一开始开发建议使用Default窗口），内容为：

RuntimeError:call_indirect to a null table entry(evaluating 'dynCall_iiii(index,a1,a2,a3)')
...(略)
1
2

Fatal error with WebGL running on 15.4？，这里找到了相关缘由，是iOS设备15.4版本的问题。

WebGL稳定性

• 不支持多线程，因为JavaScript不支持多线程，所以System.Threading命名空间下的类无法使用
• 网络协议不支持Socket。若要在WebGL下使用网络功能可以考虑使用HTTP协议，WebSocket或者WebRTC;也可以使用自带的WWW或者UnityWebRequest,它们是基于HTTP协议实现的。
• WebGL 1.0基于OpenGL ES 2.0，WebGL 2.0基于OpenGL ES 3.0，所以存在一定的限制。
• WebGL音频是基于自定义的后台，因此只具备基本的音频功能。
• WebGL是AOT，因此不能使用System.Reflection.Emit下的类型进行代码生成。

浏览器厂商为了稳定性，一般采用黑名单/白名单的方式，针对不同的显卡驱动进行功能限制，在 chrome 中可以通过输入 chrome://gpu 来查看当前 gpu 的状态，或者可以在BlacklistsAndWhitelists查询；

其它文档

Unity官方文档：WebGL
Unity WebGL 开发指北（完全篇）