当前位置：首页 > news >正文

【Unity】WebGL开发问题汇总

news 2025/5/14 6:56:29

1 前言

主要记录下WebGL开发过程中遇到的各种问题。

2 问题

2.1 中文字体不显示

问题：

经典问题了。将项目打包在WebGL平台后，运行发现所用中文字体都不现实了。

解决办法：

替换Text组件的“字体”。可以将电脑字体复制到项目当中然后替换组件的字体。电脑字体路径：C:\Windows\Fonts。也可以从网上下载一些字体。只要是能显示中文的字体就行。

2.2 缺少配置文件

问题：

运行时报错，报错内容：“Unable to parse Build/XXXXXXX.framework.js.unityweb! The file is corrupt, or compression was misconfigured? (check Content-Encoding HTTP Response Header on web server)”。

解决办法：

将web.config文件放到打包文件夹下即可。web.config内容：

<?xml version="1.0" encoding="utf-8"?>
<!--有关如何配置 ASP.NET 应用程序的详细信息，请访问https://go.microsoft.com/fwlink/?LinkId=169433
-->
<configuration><system.webServer><httpProtocol><!-- 允许跨域配置 --><customHeaders><add name="Access-Control-Allow-Origin" value="*" /><add name="Access-Control-Allow-Headers" value="X-Requested-With,Content-Type,Authorization" /><add name="Access-Control-Allow-Methods" value="GET, POST, PUT, DELETE,OPTIONS" /><add name="Access-Control-Allow-Credentials" value="true" /></customHeaders></httpProtocol><staticContent><remove fileExtension=".mem" /><remove fileExtension=".data" /><remove fileExtension=".unity3d" /><remove fileExtension=".jsbr" /><remove fileExtension=".membr" /><remove fileExtension=".databr" /><remove fileExtension=".unity3dbr" /><remove fileExtension=".jsgz" /><remove fileExtension=".memgz" /><remove fileExtension=".datagz" /><remove fileExtension=".unity3dgz" /><remove fileExtension=".json" /><remove fileExtension=".unityweb" /><mimeMap fileExtension=".mem" mimeType="application/octet-stream" /><mimeMap fileExtension=".data" mimeType="application/octet-stream" /><mimeMap fileExtension=".unity3d" mimeType="application/octet-stream" /><mimeMap fileExtension=".jsbr" mimeType="application/octet-stream" /><mimeMap fileExtension=".membr" mimeType="application/octet-stream" /><mimeMap fileExtension=".databr" mimeType="application/octet-stream" /><mimeMap fileExtension=".unity3dbr" mimeType="application/octet-stream" /><mimeMap fileExtension=".jsgz" mimeType="application/x-javascript; charset=UTF-8" /><mimeMap fileExtension=".memgz" mimeType="application/octet-stream" /><mimeMap fileExtension=".datagz" mimeType="application/octet-stream" /><mimeMap fileExtension=".unity3dgz" mimeType="application/octet-stream" /><mimeMap fileExtension=".json" mimeType="application/json; charset=UTF-8" /><mimeMap fileExtension=".unityweb" mimeType="application/octet-stream" /><!--<remove fileExtension=".*"/><mimeMap fileExtension=".*" mimeType="*/*"/>--></staticContent><!--<directoryBrowse enabled="true" />--></system.webServer>
</configuration>

注释内容是解决另一问题的方法（见2.3）。

2.3 无法访问Web文件

问题：

无法访问通过网络地址访问的文件。

当我们自己搭一个本地网站用于访问相关文件时便会出这种错误。如图：

或者是在打包的WebGL项目中通过网络地址访问文件时，也会报错。不过这种错误是在运行中的错误，会以项目所提供的报错方式来报错，或者在F12的控制台中可看到对于某个地址文件的“Error : HTTP/1.1 404 Not Found”错误。

解决方法：

在web.config配置文件中（见2.2），添加一些内容。对于网站，应在网站文件夹内添加此配置文件。对于WebGL项目的访问，若是网站则同前面，若是自己的StreamingAssets文件夹内的内容，则配置文件应添加到此WebGL项目所打包生成并用于部署的文件夹内（StreamingAssets问题见2.7）。

web.config内容：

<?xml version="1.0" encoding="utf-8"?>
<!--有关如何配置 ASP.NET 应用程序的详细信息，请访问https://go.microsoft.com/fwlink/?LinkId=169433
-->
<configuration><system.webServer><httpProtocol><!-- 允许跨域配置 --><customHeaders><add name="Access-Control-Allow-Origin" value="*" /><add name="Access-Control-Allow-Headers" value="X-Requested-With,Content-Type,Authorization" /><add name="Access-Control-Allow-Methods" value="GET, POST, PUT, DELETE,OPTIONS" /><add name="Access-Control-Allow-Credentials" value="true" /></customHeaders></httpProtocol><staticContent><remove fileExtension=".mem" /><remove fileExtension=".data" /><remove fileExtension=".unity3d" /><remove fileExtension=".jsbr" /><remove fileExtension=".membr" /><remove fileExtension=".databr" /><remove fileExtension=".unity3dbr" /><remove fileExtension=".jsgz" /><remove fileExtension=".memgz" /><remove fileExtension=".datagz" /><remove fileExtension=".unity3dgz" /><remove fileExtension=".json" /><remove fileExtension=".unityweb" /><mimeMap fileExtension=".mem" mimeType="application/octet-stream" /><mimeMap fileExtension=".data" mimeType="application/octet-stream" /><mimeMap fileExtension=".unity3d" mimeType="application/octet-stream" /><mimeMap fileExtension=".jsbr" mimeType="application/octet-stream" /><mimeMap fileExtension=".membr" mimeType="application/octet-stream" /><mimeMap fileExtension=".databr" mimeType="application/octet-stream" /><mimeMap fileExtension=".unity3dbr" mimeType="application/octet-stream" /><mimeMap fileExtension=".jsgz" mimeType="application/x-javascript; charset=UTF-8" /><mimeMap fileExtension=".memgz" mimeType="application/octet-stream" /><mimeMap fileExtension=".datagz" mimeType="application/octet-stream" /><mimeMap fileExtension=".unity3dgz" mimeType="application/octet-stream" /><mimeMap fileExtension=".json" mimeType="application/json; charset=UTF-8" /><mimeMap fileExtension=".unityweb" mimeType="application/octet-stream" /><remove fileExtension=".*"/><!--添加--><mimeMap fileExtension=".*" mimeType="*/*"/><!--添加--></staticContent><directoryBrowse enabled="true" /><!--添加--></system.webServer>
</configuration>

在某位处，添加了三行内容。

2.4 YooAsset资源加载同步不可用

问题：

在使用YooAsset资源管理时，若使用同步方式加载资源，资源加载失败并报错。

解决方法：

使用异步呗。

PS：

值得一提，Unity自身的Resources资源加载方式可以使用同步加载。

2.5 多线程不可用

问题：

在WebGL平台下，多线程无法使用。

解决方法：

使用Unity协程替代。

2.6 WebSocket不可用

问题：

WebGL下，System.Net.WebSockets命名空间下的WebSocket方案不可用。

解决方法：

可使用部分插件来实现WebSocket通信。【Unity】Kafka、Mqtt、Wesocket通信

PS：

UnityEngine.Networking下的UnityWebRequest类可用于Http请求。

2.7 StreamingAssets文件操作

问题：

在WebGL平台中，System.IO文件操作接口不可用，同时StreamingAssets路径映射规则改变。

比如在StreamingAssets有一个文件路径为：Assets/StreamingAssets/GameAsset/test.txt。那么其在WebGL平台的路径应为：<网络地址>/StreamingAssets/GameAsset/test.txt。原来是盘符开头的本地地址，现在则是http/https开头的网络地址。

解决方案：

使用文件的网络地址，以及Http请求来访问文件。这里分为文本文件与Html文件来讨论。

1、文本文件

核心模块：

public class WebFileReader : SingletonMono<WebFileReader>
{public void ReadTextFile(string relativePath, Action<string> callback){StartCoroutine(ReadTextCoroutine(relativePath, callback));}private IEnumerator ReadTextCoroutine(string relativePath, Action<string> callback){string fullPath = Path.Combine(Application.streamingAssetsPath, relativePath.TrimStart('/'));UnityWebRequest request = UnityWebRequest.Get(fullPath);yield return request.SendWebRequest();if(request.result == UnityWebRequest.Result.Success){callback?.Invoke(request.downloadHandler.text);}else{Debug.LogError($"文件读取失败: {fullPath}\n错误信息: {request.error}");callback?.Invoke(null);}}
}

使用示例：

// 配置文件读取
void LoadServiceConfig()
{WebFileReader.Instance.ReadTextFile("Config/serverconfig.json", (json) => {if(!string.IsNullOrEmpty(json)){serviceConfig = JsonUtility.FromJson<ServiceConfig>(json);Debug.Log($"服务器地址: {serviceConfig.apiEndpoint}");}else{Debug.LogWarning("使用默认配置文件");serviceConfig = GetDefaultConfig();}});
}

2、Html文件

路径构建规范：

public class WebUrlBuilder
{public static string BuildHtmlPath(string relativePath){return Path.Combine(Application.streamingAssetsPath, relativePath).Replace("\\", "/")  // 统一路径格式.TrimEnd('/');      // 移除末尾分隔符}
}

参数化URL，调用：

[Serializable]
public class UserData 
{public string userId;public string sessionToken;
}void OpenWebDashboard(UserData user)
{string baseUrl = WebUrlBuilder.BuildHtmlPath("Dashboard/index.html");// 使用WWW.EscapeURL处理特殊字符string parameters = $"?userId={WWW.EscapeURL(user.userId)}" +$"&token={WWW.EscapeURL(user.sessionToken)}";Application.OpenURL(baseUrl + parameters);
}

PS：

个人觉得，像通过YooAsset、Resources等方式加载资源这种都是本地加载，而上述的StreamingAssets内文件访问这种本质应该是对网络端文件的访问，而非本地，这点要区分下。

参考：Unity WebGL环境下StreamingAssets文件操作