1. 项目概述为什么WebGL项目需要异步存储如果你正在用Unity开发WebGL游戏或应用并且被“数据保存”这个问题卡过脖子那你肯定懂我在说什么。WebGL环境运行在浏览器这个沙盒里它不像PC或移动端那样能直接读写本地文件系统。你辛辛苦苦让玩家打了一下午的进度刷新一下页面没了——这种体验足以劝退大部分用户。传统的PlayerPrefs在WebGL上虽然能用但它本质上是同步的数据量一大或者网络稍有波动整个主线程就可能被卡住导致页面直接“白屏”或“卡死”体验极其糟糕。这就是“UniTask WebGL异步存储”要解决的核心痛点。它不是一个全新的存储技术而是一套架构思路和实现方案核心是利用C#的async/await异步编程模型、Unity的UnityWebRequest或Fetch API以及浏览器的IndexedDB构建一个在WebGL环境下真正非阻塞、高性能、可靠的本地数据管理方案。简单说就是把那些耗时的IO操作读、写、删全部丢到后台线程Web Worker模拟或异步任务里去确保游戏主循环丝般顺滑。最近很多团队都在尝试将更复杂的应用比如带有大地图、大量实体标注的工具类似“百度地图WebGL点聚合优化”中处理海量数据点的思路搬到网页端。这类应用对本地缓存如用户配置、地图瓦片、离线数据的需求非常旺盛。一个高效的异步存储系统就是支撑这类复杂WebGL应用体验的基石。它解决的不仅是“存不存得住”的问题更是“存得快不快、会不会卡”的问题。2. 核心架构设计与技术选型为什么是这套组合拳我们得拆开看。在WebGL里操作本地数据你有几个选择PlayerPrefs、LocalStorage、IndexedDB甚至Cookies。2.1 存储介质选型为什么是IndexedDBPlayerPrefs(WebGL后端为LocalStorage)最方便Unity原生支持。但它是同步的且存储空间很小通常5MB左右。当你存一个几MB的存档时主线程会等待整个写入完成期间任何输入、渲染都会停止。对于需要缓存大量资源如用户生成内容、离线地图的项目这绝对是灾难。LocalStorage和PlayerPrefs的WebGL后端一样同步、容量小5-10MB、仅支持字符串。直接Pass。Cookies容量更小4KB每次HTTP请求都会携带完全不适合存应用数据。IndexedDB这才是主角。它是一个异步的、事务型的浏览器内数据库支持存储大量结构化数据包括File、Blob对象理论存储空间很大通常是硬盘空间的50%以上。异步意味着它的操作不会阻塞页面渲染这正是我们追求的核心特性。所以技术选型很明确利用IndexedDB作为底层存储引擎。2.2 异步桥梁选型为什么是UniTask UnityWebRequest/Fetch选定了仓库我们还需要一个在C#Unity和JavaScriptIndexedDB之间高效、安全通信的桥梁。传统方式JS - C#通过[DllImport(“__Internal”)]调用C# - JS通过Application.ExternalEval。这种方式比较原始回调管理麻烦容易写出“回调地狱”。现代方式UnityWebRequest或Fetch API。我们可以创建一个极简的HTTP服务器运行在Web Worker中或者直接通过unityInstance.Module调用编译后的JavaScript函数。更优雅的方式是用UnityWebRequest向一个虚拟的URL发送请求这个请求被JavaScript拦截并处理然后返回结果。这听起来绕但能更好地利用Unity现有的异步体系和错误处理机制。异步编程模型UniTask。C#原生的Task在Unity的旧版本WebGL支持上有一些坑点而UniTask为Unity做了深度优化性能更好与Unity协程、生命周期集成更紧密。用UniTask来封装我们的异步存储操作代码会变得非常清晰就像在写普通的异步C#代码一样彻底告别回调。因此架构图就清晰了C#业务层调用诸如SaveAsync(“key”, data)的方法。C#接口层将数据序列化如用JsonUtility或MessagePack通过UniTask包装的UnityWebRequest或直接JS调用发起异步请求。JavaScript桥接层在浏览器中接收请求调用IndexedDB的API进行实际读写。IndexedDB存储层完成数据持久化。结果返回JavaScript将结果或错误通过桥接层返回给C#UniTask完成await状态业务层继续执行。注意这里有一个关键细节WebGL中不能直接操作复杂的C#对象指针或引用传递给JS。所有需要存储的数据必须被序列化为一个字符串或字节数组。通常使用JsonUtility.ToJson()或更高效的二进制序列化库如MessagePack-CSharp。3. 分步实现与核心代码解析理论说完了我们直接上干货看看怎么一步步把它搭起来。我会用一个保存玩家存档包含角色名、等级、金币和物品列表的例子来演示。3.1 第一步创建JavaScript桥接文件首先我们需要一个.jslib或.jspre文件放在Assets的Plugins文件夹下作为C#调用JavaScript的桥梁。WebGLStorage.jslibmergeInto(LibraryManager.library, { // 初始化数据库 DB_Initialize: function() { return new Promise((resolve, reject) { const request indexedDB.open(‘UnityWebGL_Save’, 1); request.onerror (event) reject(“IndexedDB open error: ” event.target.error); request.onsuccess (event) { window._unityDB event.target.result; // 全局保存引用 resolve(); }; request.onupgradeneeded (event) { const db event.target.result; if (!db.objectStoreNames.contains(‘saves’)) { db.createObjectStore(‘saves’, { keyPath: ‘key’ }); } }; }).then(() 0).catch(err { console.error(err); return -1; }); }, // 异步保存数据字符串 DB_SaveAsync: function (keyPtr, dataPtr) { const key Pointer_stringify(keyPtr); const data Pointer_stringify(dataPtr); return new Promise((resolve, reject) { const transaction window._unityDB.transaction([‘saves’], ‘readwrite’); const store transaction.objectStore(‘saves’); const request store.put({ key: key, value: data }); request.onsuccess () resolve(0); request.onerror (event) reject(“Save error: ” event.target.error); }).then(() 0).catch(err { console.error(err); return -1; }); }, // 异步加载数据 DB_LoadAsync: function (keyPtr) { const key Pointer_stringify(keyPtr); return new Promise((resolve, reject) { const transaction window._unityDB.transaction([‘saves’], ‘readonly’); const store transaction.objectStore(‘saves’); const request store.get(key); request.onsuccess () { const result request.result ? request.result.value : null; // 这里需要将字符串结果返回给C#比较复杂通常需要分配内存并拷贝字符串。 // 更常见的做法是让C#侧通过回调函数来接收字符串。 // 为简化示例我们假设通过另一种方式通信如下文的UnityWebRequest方式。 resolve(result); }; request.onerror (event) reject(“Load error: ” event.target.error); }).then((result) { // 临时方案将结果存入一个全局变量供C#另一函数读取 window._lastLoadResult result; return result null ? -2 : 0; // -2表示未找到 }).catch(err { console.error(err); return -1; }); }, // C#调用此函数来获取刚才加载的字符串结果 DB_GetLoadResult: function () { const result window._lastLoadResult || ‘’; window._lastLoadResult null; const buffer _malloc(result.length 1); writeStringToMemory(result, buffer); return buffer; } });实操心得直接使用.jslib进行复杂的字符串和异步结果传递非常繁琐容易内存泄漏。上述DB_LoadAsync和DB_GetLoadResult的拆分是一种妥协方案。在生产环境中我更推荐使用UnityWebRequest与一个内置的虚拟HTTP端点通信这样可以利用Unity内置的异步和字符串处理机制更安全也更方便。下文将介绍这种更优方案。3.2 第二步使用UnityWebRequest作为通信层推荐我们可以在JavaScript中创建一个简单的消息路由器拦截特定的UnityWebRequest。修改后的JavaScript (通过index.html或单独的.js文件加载)script // 在Unity实例化后注册处理器 document.addEventListener(‘UnityLoaded’, function() { const unityInstance unityFramework.UnityLoader.instantiate(…); // 重写UnityWebRequest的Send方法简化示例实际需更健壮 const originalSend unityInstance.Module.WebRequest.send; unityInstance.Module.WebRequest.send function(webRequestId, data, dataLength) { const request unityInstance.Module.WebRequest.GetRequest(webRequestId); const url request.url; // 拦截我们自定义协议的请求例如 ‘webgl-storage://save’ if (url.startsWith(‘webgl-storage://’)) { const command url.replace(‘webgl-storage://’, ‘’); const body unityInstance.Module.UTF8ToString(data, dataLength); // 获取请求体 // 处理命令 handleStorageCommand(command, body).then(response { // 成功完成WebRequest request.complete(200, ‘OK’, response); }).catch(error { // 失败完成WebRequest并传递错误 request.complete(500, ‘Internal Error’, error.toString()); }); return; // 拦截不发送真实网络请求 } // 非拦截的请求走原逻辑 originalSend.call(this, webRequestId, data, dataLength); }; async function handleStorageCommand(command, bodyJson) { const db await getDB(); const parsed JSON.parse(bodyJson); const { key, value } parsed; switch(command) { case ‘save’: await saveToDB(db, key, value); return ‘OK’; case ‘load’: const data await loadFromDB(db, key); return JSON.stringify({ success: true, data: data }); case ‘delete’: await deleteFromDB(db, key); return ‘OK’; default: throw new Error(Unknown command: ${command}); } } // 封装的IndexedDB操作 function getDB() { /* … 返回打开的数据库Promise … */ } function saveToDB(db, key, value) { /* … */ } function loadFromDB(db, key) { /* … */ } function deleteFromDB(db, key) { /* … */ } }); /script3.3 第三步实现C#端的UniTask异步存储管理器现在我们来编写C#核心代码。WebGLAsyncStorage.csusing System; using System.Text; using System.Threading; using UnityEngine; using UnityEngine.Networking; using Cysharp.Threading.Tasks; [System.Serializable] public class SaveData { public string playerName; public int level; public int gold; public Liststring inventory; } public class WebGLAsyncStorage { private const string BaseUrl “webgl-storage://”; // 初始化确保数据库就绪可在游戏启动时调用一次 public static async UniTaskbool InitializeAsync(CancellationToken ct default) { // 这里可以发送一个ping命令测试连通性 try { var request new UnityWebRequest(BaseUrl “ping”, “GET”); request.downloadHandler new DownloadHandlerBuffer(); await request.SendWebRequest().WithCancellation(ct); return request.responseCode 200; } catch (Exception e) { Debug.LogError($“Storage初始化失败: {e.Message}”); return false; } } // 异步保存 public static async UniTask SaveAsyncT(string key, T data, CancellationToken ct default) where T : class { if (string.IsNullOrEmpty(key)) throw new ArgumentNullException(nameof(key)); string json JsonUtility.ToJson(data); string payload JsonUtility.ToJson(new { key, value json }); // 包装key和value using (var request CreateRequest(“save”, “POST”, payload)) { await request.SendWebRequest().WithCancellation(ct); if (request.result ! UnityWebRequest.Result.Success) { throw new Exception($“保存失败 ({request.responseCode}): {request.error}”); } Debug.Log($“数据已保存: {key}”); } } // 异步加载 public static async UniTaskT LoadAsyncT(string key, CancellationToken ct default) where T : class, new() { if (string.IsNullOrEmpty(key)) throw new ArgumentNullException(nameof(key)); string payload JsonUtility.ToJson(new { key }); using (var request CreateRequest(“load”, “POST”, payload)) { await request.SendWebRequest().WithCancellation(ct); if (request.result ! UnityWebRequest.Result.Success) { throw new Exception($“加载失败 ({request.responseCode}): {request.error}”); } var response JsonUtility.FromJsonLoadResponse(request.downloadHandler.text); if (response.success !string.IsNullOrEmpty(response.data)) { return JsonUtility.FromJsonT(response.data); } else { return null; // 或 throw new KeyNotFoundException(key); } } } // 异步删除 public static async UniTask DeleteAsync(string key, CancellationToken ct default) { // 实现类似SaveAsync命令改为”delete” // … } private static UnityWebRequest CreateRequest(string command, string method, string jsonBody null) { var url BaseUrl command; var request new UnityWebRequest(url, method); if (!string.IsNullOrEmpty(jsonBody)) { byte[] bodyRaw Encoding.UTF8.GetBytes(jsonBody); request.uploadHandler new UploadHandlerRaw(bodyRaw); request.SetRequestHeader(“Content-Type”, “application/json”); } request.downloadHandler new DownloadHandlerBuffer(); return request; } [System.Serializable] private class LoadResponse { public bool success; public string data; } }3.4 第四步在游戏逻辑中使用现在在MonoBehaviour中使用就非常优雅了public class PlayerManager : MonoBehaviour { private CancellationTokenSource _cts; void Start() { _cts new CancellationTokenSource(); // 初始化存储系统 WebGLAsyncStorage.InitializeAsync(_cts.Token).Forget(); // Forget()表示不等待后台执行 } // 保存玩家数据 public async UniTaskVoid SavePlayerDataAsync() { var saveData new SaveData { playerName “冒险者”, level 99, gold 99999, inventory new Liststring { “传奇之剑”, “生命药水x10” } }; try { await WebGLAsyncStorage.SaveAsync(“player_save”, saveData, _cts.Token); Debug.Log(“存档成功”); // 这里可以更新UI比如显示“保存成功”的提示 } catch (Exception e) { Debug.LogError($“存档失败: {e.Message}”); // 处理错误例如提示玩家“保存失败请检查网络或存储空间” } } // 加载玩家数据 public async UniTaskSaveData LoadPlayerDataAsync() { try { var data await WebGLAsyncStorage.LoadAsyncSaveData(“player_save”, _cts.Token); if (data ! null) { Debug.Log($“加载成功角色:{data.playerName}, 等级:{data.level}”); return data; } else { Debug.Log(“未找到存档使用默认数据。”); return CreateDefaultData(); } } catch (Exception e) { Debug.LogError($“加载失败: {e.Message}”); return CreateDefaultData(); // 失败时返回默认数据 } } void OnDestroy() { _cts?.Cancel(); _cts?.Dispose(); } }4. 性能优化与高级技巧基础功能实现了但要投入生产环境我们还得考虑更多。4.1 数据序列化优化JsonUtility虽然方便但性能并非最优生成的JSON体积也较大。对于复杂或庞大的数据比如一个包含数百个单位的策略游戏存档建议使用MessagePack或Protocol Buffers。MessagePack-CSharp二进制序列化速度极快体积比JSON小很多。在WebGL中传输字节数组比传输大字符串效率更高。实现方式在SaveAsync内部将T data先用MessagePackSerializer.Serialize()转为byte[]然后可以将其转换为Base64字符串如果JS端处理字符串更方便或直接通过UnityWebRequest的UploadHandlerRaw发送字节。在JS端IndexedDB可以存储Blob或ArrayBuffer能原生保存二进制数据。4.2 批量操作与事务频繁的单个保存/加载操作会产生大量微小的事务影响性能。可以设计批量操作API。public static async UniTask SaveBatchAsync(Dictionarystring, object keyValuePairs, CancellationToken ct default) { // 将多个键值对打包成一个请求体 // JS端在一个IndexedDB事务中处理所有操作 }在JavaScript端确保将多个put或get操作放在同一个transaction中能显著提升效率。4.3 容错与降级策略超时控制为每个UniTask操作设置超时使用UniTask.Timeout。try { await WebGLAsyncStorage.LoadAsync(…).Timeout(TimeSpan.FromSeconds(5)); } catch (TimeoutException) { // 降级使用内存缓存或默认值 }降级存储如果IndexedDB初始化失败可能用户禁用或无痕模式可以降级到LocalStorage同步需小心使用或纯内存缓存并提示用户功能受限。数据校验与版本化存储的数据结构可能随游戏版本变化。在序列化的数据中加入版本号字段加载时进行校验和迁移。4.4 内存与泄漏管理取消令牌CancellationToken务必在MonoBehaviour的OnDestroy中取消发出的异步操作防止游戏对象销毁后回调继续执行导致错误或泄漏。UnityWebRequest释放using语句确保了UnityWebRequest的及时释放。这是必须遵守的好习惯。JavaScript端清理确保JS端没有残留的全局变量或闭包引用防止内存无法被垃圾回收。5. 实战避坑指南与常见问题这里是我在多个项目中踩过的坑希望能帮你省下大量调试时间。5.1 跨域与安全限制问题你的webgl-storage://协议是虚拟的但如果你在JS中尝试使用真实的fetch或XMLHttpRequest访问file://或其它域会遇到CORS错误。解决所有与存储相关的通信必须严格控制在同一页面内的Unity实例与JS之间。使用UnityWebRequest拦截方案是最安全的因为它完全在Unity的环境内。5.2 IndexedDB的异步性与事务生命周期问题IndexedDB的操作onsuccess,onerror是真正的异步回调。如果你在JS桥接函数中试图“同步”地返回结果给C#几乎一定会失败。解决永远使用Promise或async/await包装所有IndexedDB操作并通过回调机制如我们设计的UnityWebRequest完成回调将结果传回C#。不要试图在C#的[DllImport]函数中等待JS的异步操作。5.3 数据大小限制与清理问题虽然IndexedDB容量很大但浏览器对单个源的总存储空间仍有配额通常是硬盘的某个百分比。无节制地存储比如缓存无数高清图片会导致QuotaExceededError。解决实现存储空间监控。可以通过navigator.storage.estimate().then(estimate …)查询已用和剩余空间。实现LRU最近最少使用清理策略自动清理旧缓存。对存储的数据进行压缩如使用pako库进行gzip压缩后再存。5.4 浏览器隐私模式与数据持久性问题在浏览器的隐私模式无痕模式下IndexedDB可能被禁用或者页面关闭后数据被立即清除。解决在InitializeAsync时进行能力检测。如果失败向玩家显示友好提示“当前处于隐私浏览模式存档功能可能无法使用”并启用降级方案如内存存档提示玩家频繁手动导出。5.5 UniTask与WebGL构建的兼容性问题旧版本Unity或特定构建设置下UniTask的某些UniTask方法在WebGL上可能无法正常工作。解决确保使用最新稳定版的UniTask。在Player Settings的Scripting Backend中确保使用Mono而不是IL2CPP截至Unity 2021 LTSWebGL对IL2CPP的异步支持已大幅改善但Mono通常更稳定。如果遇到奇怪的编译错误尝试在项目设置中明确添加UNITY_WEBGL宏定义并为WebGL平台编写特定的兼容代码。5.6 调试技巧Chrome DevTools在Application-Storage-IndexedDB中你可以直观地查看、编辑、删除我们存储的所有数据这对调试至关重要。Unity WebGL Console确保浏览器控制台Console是打开的所有JS端的console.log和错误都会在这里显示。网络请求查看在Network标签页中你可以过滤出webgl-storage://的请求查看请求和响应体排查通信问题。这套“UniTask WebGL异步存储”方案从最初的为解决卡顿而生的简单想法到现在能支撑起包含大量用户生成内容的复杂项目其核心价值就在于将异步思想贯穿始终。它不仅仅是一个工具类更是一种适用于WebGL这种特殊环境的架构范式。当你习惯了用await去处理所有IO后你会发现WebGL应用的流畅度和健壮性都能提升一个档次。
Unity WebGL异步存储方案：基于UniTask与IndexedDB实现高性能数据持久化
1. 项目概述为什么WebGL项目需要异步存储如果你正在用Unity开发WebGL游戏或应用并且被“数据保存”这个问题卡过脖子那你肯定懂我在说什么。WebGL环境运行在浏览器这个沙盒里它不像PC或移动端那样能直接读写本地文件系统。你辛辛苦苦让玩家打了一下午的进度刷新一下页面没了——这种体验足以劝退大部分用户。传统的PlayerPrefs在WebGL上虽然能用但它本质上是同步的数据量一大或者网络稍有波动整个主线程就可能被卡住导致页面直接“白屏”或“卡死”体验极其糟糕。这就是“UniTask WebGL异步存储”要解决的核心痛点。它不是一个全新的存储技术而是一套架构思路和实现方案核心是利用C#的async/await异步编程模型、Unity的UnityWebRequest或Fetch API以及浏览器的IndexedDB构建一个在WebGL环境下真正非阻塞、高性能、可靠的本地数据管理方案。简单说就是把那些耗时的IO操作读、写、删全部丢到后台线程Web Worker模拟或异步任务里去确保游戏主循环丝般顺滑。最近很多团队都在尝试将更复杂的应用比如带有大地图、大量实体标注的工具类似“百度地图WebGL点聚合优化”中处理海量数据点的思路搬到网页端。这类应用对本地缓存如用户配置、地图瓦片、离线数据的需求非常旺盛。一个高效的异步存储系统就是支撑这类复杂WebGL应用体验的基石。它解决的不仅是“存不存得住”的问题更是“存得快不快、会不会卡”的问题。2. 核心架构设计与技术选型为什么是这套组合拳我们得拆开看。在WebGL里操作本地数据你有几个选择PlayerPrefs、LocalStorage、IndexedDB甚至Cookies。2.1 存储介质选型为什么是IndexedDBPlayerPrefs(WebGL后端为LocalStorage)最方便Unity原生支持。但它是同步的且存储空间很小通常5MB左右。当你存一个几MB的存档时主线程会等待整个写入完成期间任何输入、渲染都会停止。对于需要缓存大量资源如用户生成内容、离线地图的项目这绝对是灾难。LocalStorage和PlayerPrefs的WebGL后端一样同步、容量小5-10MB、仅支持字符串。直接Pass。Cookies容量更小4KB每次HTTP请求都会携带完全不适合存应用数据。IndexedDB这才是主角。它是一个异步的、事务型的浏览器内数据库支持存储大量结构化数据包括File、Blob对象理论存储空间很大通常是硬盘空间的50%以上。异步意味着它的操作不会阻塞页面渲染这正是我们追求的核心特性。所以技术选型很明确利用IndexedDB作为底层存储引擎。2.2 异步桥梁选型为什么是UniTask UnityWebRequest/Fetch选定了仓库我们还需要一个在C#Unity和JavaScriptIndexedDB之间高效、安全通信的桥梁。传统方式JS - C#通过[DllImport(“__Internal”)]调用C# - JS通过Application.ExternalEval。这种方式比较原始回调管理麻烦容易写出“回调地狱”。现代方式UnityWebRequest或Fetch API。我们可以创建一个极简的HTTP服务器运行在Web Worker中或者直接通过unityInstance.Module调用编译后的JavaScript函数。更优雅的方式是用UnityWebRequest向一个虚拟的URL发送请求这个请求被JavaScript拦截并处理然后返回结果。这听起来绕但能更好地利用Unity现有的异步体系和错误处理机制。异步编程模型UniTask。C#原生的Task在Unity的旧版本WebGL支持上有一些坑点而UniTask为Unity做了深度优化性能更好与Unity协程、生命周期集成更紧密。用UniTask来封装我们的异步存储操作代码会变得非常清晰就像在写普通的异步C#代码一样彻底告别回调。因此架构图就清晰了C#业务层调用诸如SaveAsync(“key”, data)的方法。C#接口层将数据序列化如用JsonUtility或MessagePack通过UniTask包装的UnityWebRequest或直接JS调用发起异步请求。JavaScript桥接层在浏览器中接收请求调用IndexedDB的API进行实际读写。IndexedDB存储层完成数据持久化。结果返回JavaScript将结果或错误通过桥接层返回给C#UniTask完成await状态业务层继续执行。注意这里有一个关键细节WebGL中不能直接操作复杂的C#对象指针或引用传递给JS。所有需要存储的数据必须被序列化为一个字符串或字节数组。通常使用JsonUtility.ToJson()或更高效的二进制序列化库如MessagePack-CSharp。3. 分步实现与核心代码解析理论说完了我们直接上干货看看怎么一步步把它搭起来。我会用一个保存玩家存档包含角色名、等级、金币和物品列表的例子来演示。3.1 第一步创建JavaScript桥接文件首先我们需要一个.jslib或.jspre文件放在Assets的Plugins文件夹下作为C#调用JavaScript的桥梁。WebGLStorage.jslibmergeInto(LibraryManager.library, { // 初始化数据库 DB_Initialize: function() { return new Promise((resolve, reject) { const request indexedDB.open(‘UnityWebGL_Save’, 1); request.onerror (event) reject(“IndexedDB open error: ” event.target.error); request.onsuccess (event) { window._unityDB event.target.result; // 全局保存引用 resolve(); }; request.onupgradeneeded (event) { const db event.target.result; if (!db.objectStoreNames.contains(‘saves’)) { db.createObjectStore(‘saves’, { keyPath: ‘key’ }); } }; }).then(() 0).catch(err { console.error(err); return -1; }); }, // 异步保存数据字符串 DB_SaveAsync: function (keyPtr, dataPtr) { const key Pointer_stringify(keyPtr); const data Pointer_stringify(dataPtr); return new Promise((resolve, reject) { const transaction window._unityDB.transaction([‘saves’], ‘readwrite’); const store transaction.objectStore(‘saves’); const request store.put({ key: key, value: data }); request.onsuccess () resolve(0); request.onerror (event) reject(“Save error: ” event.target.error); }).then(() 0).catch(err { console.error(err); return -1; }); }, // 异步加载数据 DB_LoadAsync: function (keyPtr) { const key Pointer_stringify(keyPtr); return new Promise((resolve, reject) { const transaction window._unityDB.transaction([‘saves’], ‘readonly’); const store transaction.objectStore(‘saves’); const request store.get(key); request.onsuccess () { const result request.result ? request.result.value : null; // 这里需要将字符串结果返回给C#比较复杂通常需要分配内存并拷贝字符串。 // 更常见的做法是让C#侧通过回调函数来接收字符串。 // 为简化示例我们假设通过另一种方式通信如下文的UnityWebRequest方式。 resolve(result); }; request.onerror (event) reject(“Load error: ” event.target.error); }).then((result) { // 临时方案将结果存入一个全局变量供C#另一函数读取 window._lastLoadResult result; return result null ? -2 : 0; // -2表示未找到 }).catch(err { console.error(err); return -1; }); }, // C#调用此函数来获取刚才加载的字符串结果 DB_GetLoadResult: function () { const result window._lastLoadResult || ‘’; window._lastLoadResult null; const buffer _malloc(result.length 1); writeStringToMemory(result, buffer); return buffer; } });实操心得直接使用.jslib进行复杂的字符串和异步结果传递非常繁琐容易内存泄漏。上述DB_LoadAsync和DB_GetLoadResult的拆分是一种妥协方案。在生产环境中我更推荐使用UnityWebRequest与一个内置的虚拟HTTP端点通信这样可以利用Unity内置的异步和字符串处理机制更安全也更方便。下文将介绍这种更优方案。3.2 第二步使用UnityWebRequest作为通信层推荐我们可以在JavaScript中创建一个简单的消息路由器拦截特定的UnityWebRequest。修改后的JavaScript (通过index.html或单独的.js文件加载)script // 在Unity实例化后注册处理器 document.addEventListener(‘UnityLoaded’, function() { const unityInstance unityFramework.UnityLoader.instantiate(…); // 重写UnityWebRequest的Send方法简化示例实际需更健壮 const originalSend unityInstance.Module.WebRequest.send; unityInstance.Module.WebRequest.send function(webRequestId, data, dataLength) { const request unityInstance.Module.WebRequest.GetRequest(webRequestId); const url request.url; // 拦截我们自定义协议的请求例如 ‘webgl-storage://save’ if (url.startsWith(‘webgl-storage://’)) { const command url.replace(‘webgl-storage://’, ‘’); const body unityInstance.Module.UTF8ToString(data, dataLength); // 获取请求体 // 处理命令 handleStorageCommand(command, body).then(response { // 成功完成WebRequest request.complete(200, ‘OK’, response); }).catch(error { // 失败完成WebRequest并传递错误 request.complete(500, ‘Internal Error’, error.toString()); }); return; // 拦截不发送真实网络请求 } // 非拦截的请求走原逻辑 originalSend.call(this, webRequestId, data, dataLength); }; async function handleStorageCommand(command, bodyJson) { const db await getDB(); const parsed JSON.parse(bodyJson); const { key, value } parsed; switch(command) { case ‘save’: await saveToDB(db, key, value); return ‘OK’; case ‘load’: const data await loadFromDB(db, key); return JSON.stringify({ success: true, data: data }); case ‘delete’: await deleteFromDB(db, key); return ‘OK’; default: throw new Error(Unknown command: ${command}); } } // 封装的IndexedDB操作 function getDB() { /* … 返回打开的数据库Promise … */ } function saveToDB(db, key, value) { /* … */ } function loadFromDB(db, key) { /* … */ } function deleteFromDB(db, key) { /* … */ } }); /script3.3 第三步实现C#端的UniTask异步存储管理器现在我们来编写C#核心代码。WebGLAsyncStorage.csusing System; using System.Text; using System.Threading; using UnityEngine; using UnityEngine.Networking; using Cysharp.Threading.Tasks; [System.Serializable] public class SaveData { public string playerName; public int level; public int gold; public Liststring inventory; } public class WebGLAsyncStorage { private const string BaseUrl “webgl-storage://”; // 初始化确保数据库就绪可在游戏启动时调用一次 public static async UniTaskbool InitializeAsync(CancellationToken ct default) { // 这里可以发送一个ping命令测试连通性 try { var request new UnityWebRequest(BaseUrl “ping”, “GET”); request.downloadHandler new DownloadHandlerBuffer(); await request.SendWebRequest().WithCancellation(ct); return request.responseCode 200; } catch (Exception e) { Debug.LogError($“Storage初始化失败: {e.Message}”); return false; } } // 异步保存 public static async UniTask SaveAsyncT(string key, T data, CancellationToken ct default) where T : class { if (string.IsNullOrEmpty(key)) throw new ArgumentNullException(nameof(key)); string json JsonUtility.ToJson(data); string payload JsonUtility.ToJson(new { key, value json }); // 包装key和value using (var request CreateRequest(“save”, “POST”, payload)) { await request.SendWebRequest().WithCancellation(ct); if (request.result ! UnityWebRequest.Result.Success) { throw new Exception($“保存失败 ({request.responseCode}): {request.error}”); } Debug.Log($“数据已保存: {key}”); } } // 异步加载 public static async UniTaskT LoadAsyncT(string key, CancellationToken ct default) where T : class, new() { if (string.IsNullOrEmpty(key)) throw new ArgumentNullException(nameof(key)); string payload JsonUtility.ToJson(new { key }); using (var request CreateRequest(“load”, “POST”, payload)) { await request.SendWebRequest().WithCancellation(ct); if (request.result ! UnityWebRequest.Result.Success) { throw new Exception($“加载失败 ({request.responseCode}): {request.error}”); } var response JsonUtility.FromJsonLoadResponse(request.downloadHandler.text); if (response.success !string.IsNullOrEmpty(response.data)) { return JsonUtility.FromJsonT(response.data); } else { return null; // 或 throw new KeyNotFoundException(key); } } } // 异步删除 public static async UniTask DeleteAsync(string key, CancellationToken ct default) { // 实现类似SaveAsync命令改为”delete” // … } private static UnityWebRequest CreateRequest(string command, string method, string jsonBody null) { var url BaseUrl command; var request new UnityWebRequest(url, method); if (!string.IsNullOrEmpty(jsonBody)) { byte[] bodyRaw Encoding.UTF8.GetBytes(jsonBody); request.uploadHandler new UploadHandlerRaw(bodyRaw); request.SetRequestHeader(“Content-Type”, “application/json”); } request.downloadHandler new DownloadHandlerBuffer(); return request; } [System.Serializable] private class LoadResponse { public bool success; public string data; } }3.4 第四步在游戏逻辑中使用现在在MonoBehaviour中使用就非常优雅了public class PlayerManager : MonoBehaviour { private CancellationTokenSource _cts; void Start() { _cts new CancellationTokenSource(); // 初始化存储系统 WebGLAsyncStorage.InitializeAsync(_cts.Token).Forget(); // Forget()表示不等待后台执行 } // 保存玩家数据 public async UniTaskVoid SavePlayerDataAsync() { var saveData new SaveData { playerName “冒险者”, level 99, gold 99999, inventory new Liststring { “传奇之剑”, “生命药水x10” } }; try { await WebGLAsyncStorage.SaveAsync(“player_save”, saveData, _cts.Token); Debug.Log(“存档成功”); // 这里可以更新UI比如显示“保存成功”的提示 } catch (Exception e) { Debug.LogError($“存档失败: {e.Message}”); // 处理错误例如提示玩家“保存失败请检查网络或存储空间” } } // 加载玩家数据 public async UniTaskSaveData LoadPlayerDataAsync() { try { var data await WebGLAsyncStorage.LoadAsyncSaveData(“player_save”, _cts.Token); if (data ! null) { Debug.Log($“加载成功角色:{data.playerName}, 等级:{data.level}”); return data; } else { Debug.Log(“未找到存档使用默认数据。”); return CreateDefaultData(); } } catch (Exception e) { Debug.LogError($“加载失败: {e.Message}”); return CreateDefaultData(); // 失败时返回默认数据 } } void OnDestroy() { _cts?.Cancel(); _cts?.Dispose(); } }4. 性能优化与高级技巧基础功能实现了但要投入生产环境我们还得考虑更多。4.1 数据序列化优化JsonUtility虽然方便但性能并非最优生成的JSON体积也较大。对于复杂或庞大的数据比如一个包含数百个单位的策略游戏存档建议使用MessagePack或Protocol Buffers。MessagePack-CSharp二进制序列化速度极快体积比JSON小很多。在WebGL中传输字节数组比传输大字符串效率更高。实现方式在SaveAsync内部将T data先用MessagePackSerializer.Serialize()转为byte[]然后可以将其转换为Base64字符串如果JS端处理字符串更方便或直接通过UnityWebRequest的UploadHandlerRaw发送字节。在JS端IndexedDB可以存储Blob或ArrayBuffer能原生保存二进制数据。4.2 批量操作与事务频繁的单个保存/加载操作会产生大量微小的事务影响性能。可以设计批量操作API。public static async UniTask SaveBatchAsync(Dictionarystring, object keyValuePairs, CancellationToken ct default) { // 将多个键值对打包成一个请求体 // JS端在一个IndexedDB事务中处理所有操作 }在JavaScript端确保将多个put或get操作放在同一个transaction中能显著提升效率。4.3 容错与降级策略超时控制为每个UniTask操作设置超时使用UniTask.Timeout。try { await WebGLAsyncStorage.LoadAsync(…).Timeout(TimeSpan.FromSeconds(5)); } catch (TimeoutException) { // 降级使用内存缓存或默认值 }降级存储如果IndexedDB初始化失败可能用户禁用或无痕模式可以降级到LocalStorage同步需小心使用或纯内存缓存并提示用户功能受限。数据校验与版本化存储的数据结构可能随游戏版本变化。在序列化的数据中加入版本号字段加载时进行校验和迁移。4.4 内存与泄漏管理取消令牌CancellationToken务必在MonoBehaviour的OnDestroy中取消发出的异步操作防止游戏对象销毁后回调继续执行导致错误或泄漏。UnityWebRequest释放using语句确保了UnityWebRequest的及时释放。这是必须遵守的好习惯。JavaScript端清理确保JS端没有残留的全局变量或闭包引用防止内存无法被垃圾回收。5. 实战避坑指南与常见问题这里是我在多个项目中踩过的坑希望能帮你省下大量调试时间。5.1 跨域与安全限制问题你的webgl-storage://协议是虚拟的但如果你在JS中尝试使用真实的fetch或XMLHttpRequest访问file://或其它域会遇到CORS错误。解决所有与存储相关的通信必须严格控制在同一页面内的Unity实例与JS之间。使用UnityWebRequest拦截方案是最安全的因为它完全在Unity的环境内。5.2 IndexedDB的异步性与事务生命周期问题IndexedDB的操作onsuccess,onerror是真正的异步回调。如果你在JS桥接函数中试图“同步”地返回结果给C#几乎一定会失败。解决永远使用Promise或async/await包装所有IndexedDB操作并通过回调机制如我们设计的UnityWebRequest完成回调将结果传回C#。不要试图在C#的[DllImport]函数中等待JS的异步操作。5.3 数据大小限制与清理问题虽然IndexedDB容量很大但浏览器对单个源的总存储空间仍有配额通常是硬盘的某个百分比。无节制地存储比如缓存无数高清图片会导致QuotaExceededError。解决实现存储空间监控。可以通过navigator.storage.estimate().then(estimate …)查询已用和剩余空间。实现LRU最近最少使用清理策略自动清理旧缓存。对存储的数据进行压缩如使用pako库进行gzip压缩后再存。5.4 浏览器隐私模式与数据持久性问题在浏览器的隐私模式无痕模式下IndexedDB可能被禁用或者页面关闭后数据被立即清除。解决在InitializeAsync时进行能力检测。如果失败向玩家显示友好提示“当前处于隐私浏览模式存档功能可能无法使用”并启用降级方案如内存存档提示玩家频繁手动导出。5.5 UniTask与WebGL构建的兼容性问题旧版本Unity或特定构建设置下UniTask的某些UniTask方法在WebGL上可能无法正常工作。解决确保使用最新稳定版的UniTask。在Player Settings的Scripting Backend中确保使用Mono而不是IL2CPP截至Unity 2021 LTSWebGL对IL2CPP的异步支持已大幅改善但Mono通常更稳定。如果遇到奇怪的编译错误尝试在项目设置中明确添加UNITY_WEBGL宏定义并为WebGL平台编写特定的兼容代码。5.6 调试技巧Chrome DevTools在Application-Storage-IndexedDB中你可以直观地查看、编辑、删除我们存储的所有数据这对调试至关重要。Unity WebGL Console确保浏览器控制台Console是打开的所有JS端的console.log和错误都会在这里显示。网络请求查看在Network标签页中你可以过滤出webgl-storage://的请求查看请求和响应体排查通信问题。这套“UniTask WebGL异步存储”方案从最初的为解决卡顿而生的简单想法到现在能支撑起包含大量用户生成内容的复杂项目其核心价值就在于将异步思想贯穿始终。它不仅仅是一个工具类更是一种适用于WebGL这种特殊环境的架构范式。当你习惯了用await去处理所有IO后你会发现WebGL应用的流畅度和健壮性都能提升一个档次。
