1. 项目概述：为什么Unity WebGL与HTML的集成如此重要？
如果你和我一样，从Unity原生平台开发转向WebGL，最初可能会觉得这不过是换了个发布平台，把游戏“放上网”而已。但真正上手后才发现，Unity WebGL与HTML的“无缝集成”远非一键构建那么简单，它直接决定了你的应用在浏览器中的加载速度、用户体验、以及与网页其他部分的交互能力。简单来说，集成做得好，你的WebGL应用就是一个流畅、可控的网页组件；做得不好，它就是一个卡顿、孤立、难以维护的“黑盒”。
这个“无缝集成”的核心，在于理解Unity WebGL构建输出的本质：它不是一个独立的可执行文件，而是一套由JavaScript驱动、运行在浏览器Canvas元素上的复杂应用。这套应用需要被恰当地“嵌入”到一个HTML页面中，并由这个页面来管理其生命周期、通信和资源。很多开发者遇到的“初始化很久”、“黑屏无响应”、“与网页交互困难”等问题，根源往往是对这个嵌入和通信机制理解不深。本文将从一个实战者的角度，拆解从构建配置、自定义模板、双向通信到性能优化的全链路，分享那些官方文档不会明说，但在实际项目中必须掌握的技巧和避坑指南。
2. 核心思路拆解：从构建产物到可交互网页组件
2.1 Unity WebGL构建输出解析：不只是几个文件
当你点击Unity的Build按钮并选择WebGL平台后，输出目录（默认是Build文件夹）里会生成一堆文件。新手容易看花眼，但核心文件就几类，理解它们是集成的第一步：
- 加载器脚本 (
xxx.loader.js): 这是入口。它负责检测浏览器兼容性、初始化WebAssembly/asm.js运行时、并启动资源下载。文件名中的xxx通常是你的产品名。 - 框架脚本 (
xxx.framework.js): Unity WebGL运行时的核心，包含了引擎的大部分逻辑。在启用代码分包（如Unity 2021.2+的Compression Format设置为Brotli）时，可能还会有xxx.framework.js.br等压缩变体。 - 数据文件 (
xxx.data): 这是一个包含你项目中所有场景、资源（纹理、模型、音频等）的二进制包。它的体积通常最大，是优化加载速度的关键。 - 代码文件 (
xxx.wasm或xxx.js): 这是你编写的C#脚本编译后的逻辑。如果构建目标支持WebAssembly（现代浏览器默认），就是.wasm文件，否则是.js（asm.js）文件。 - JSON配置文件 (
xxx.json): 包含构建的元数据，如内存大小(TOTAL_MEMORY)、是否使用线程等，供加载器读取。 index.html: 这是包裹上述所有内容的“外壳”。Unity会根据你选择的模板生成一个默认的HTML文件。
关键认知：Unity的构建过程，本质上是将你的游戏逻辑（C#）和资源，编译成能被JavaScript解释和调用的格式（WASM），并打包进一个数据文件。而index.html和加载器脚本，就是启动这个“虚拟机”并喂给它资源的引导程序。我们所说的“集成”，大部分工作就是定制这个引导程序（HTML模板）以及建立它与“虚拟机”（Unity内容）之间的通信桥梁。
2.2 集成架构设计：三种常见模式与选择
根据你的项目需求，集成模式大致分为三种，选择哪种决定了后续的工作量和技术路径：
- 简单嵌入模式：使用Unity默认或轻微修改的模板，将整个
Build文件夹上传到服务器，用户访问一个独立的HTML页面来运行应用。这适用于简单的展示、小游戏或原型。优点是快，缺点是与宿主页面交互能力弱，样式定制受限。 - 定制模板深度集成模式：创建自定义的WebGL模板，完全控制HTML/CSS/JS的结构和样式。Unity内容作为页面中的一个
<canvas>元素存在，你可以围绕它设计复杂的UI（如用HTML做游戏大厅、商城、用户信息面板）。这是大多数中重度网页游戏或交互应用的选择。 - 多实例与动态加载模式：在一个页面内嵌入多个Unity WebGL实例，或者根据用户操作动态加载/卸载不同的Unity应用。这对技术架构要求最高，需要精细的内存管理和实例生命周期控制，常用于复杂的网页编辑器或包含多个独立模块的应用。
对于追求“无缝集成”的项目，模式2是必由之路。模式3则是模式2的进阶应用。下文将主要围绕模式2展开。
3. 实战第一步：创建与理解自定义WebGL模板
3.1 创建自定义模板的标准化流程
Unity官方手册提到了创建模板，但有些细节需要实战补充。以下是创建并应用一个自定义模板的完整步骤：
- 定位默认模板：首先，找到Unity安装目录下的默认模板，路径通常为
<Unity安装路径>/Editor/Data/PlaybackEngines/WebGLSupport/BuildTools/WebGLTemplates/。你会看到Default和Minimal等文件夹。Minimal模板是最精简的，是学习的好起点。 - 在项目中创建模板目录：在你的Unity项目根目录的
Assets文件夹下，创建一个名为WebGLTemplates的文件夹。注意，文件夹名称必须精确。 - 复制并创建自定义模板：将
Minimal（或Default）整个文件夹复制到你的Assets/WebGLTemplates/目录下。将其重命名为有意义的名称，例如MyCustomTemplate。现在，你的模板结构应该是：Assets/WebGLTemplates/MyCustomTemplate/。 - 修改模板内容：这个
MyCustomTemplate文件夹就是一个完整的模板。其核心是index.html文件，还可以包含css、js、images等子文件夹来存放样式、脚本和图片资源。 - 在Unity中启用模板：打开
Project Settings -> Player，在Resolution and Presentation面板下，找到WebGL Template下拉菜单。你应该能看到你刚创建的MyCustomTemplate选项，选择它。 - 添加缩略图（可选但推荐）：在
MyCustomTemplate文件夹内放置一个128x128像素的PNG图片，并命名为thumbnail.png。这样在Unity的模板下拉菜单中就能看到预览图，便于管理。
实操心得：我习惯以
Minimal模板为基础进行修改，因为它代码最干净，没有多余的UI元素干扰。Default模板包含进度条和标题，如果你需要这些，可以基于它修改，但通常我们会用自己设计的HTML UI来替代。
3.2 解密模板引擎：预处理变量与条件指令
这是自定义模板的灵魂。Unity在构建时，不是简单复制你的index.html，而是会先进行“预处理”，替换其中的特殊标记。理解这些标记是编写动态模板的关键。
核心预处理变量：这些是Unity内置的，会在构建时被替换为实际值。在index.html中，它们被三层花括号包裹：{{{ VARIABLE_NAME }}}。
{{{ PRODUCT_NAME }}}：项目设置中的产品名。{{{ WIDTH }}}和{{{ HEIGHT }}}：Canvas的默认宽高。{{{ BACKGROUND_COLOR }}}：背景色（十六进制）。{{{ TOTAL_MEMORY }}}：WebGL内存堆的初始大小（字节）。这是性能调优的关键参数，设置过小会导致内存不足崩溃，过大则浪费且可能初始化慢。{{{ LOADER_FILENAME }}},{{{ DATA_FILENAME }}},{{{ FRAMEWORK_FILENAME }}},{{{ CODE_FILENAME }}}：对应构建输出文件的文件名。务必使用这些变量，而不是写死文件名，因为文件名可能因构建设置（如开发模式、代码混淆）而变化。{{{ DEVELOPMENT_PLAYER }}}：是否为开发构建。可用于在模板中插入调试工具或显示不同的UI。
用法示例：
<title>{{{ PRODUCT_NAME }}} - 我的精彩游戏</title> ... <canvas id="unity-canvas" width="{{{ WIDTH }}}" height="{{{ HEIGHT }}}"></canvas> ... <script src="{{{ LOADER_FILENAME }}}"></script>条件指令：这让你能根据构建配置动态生成HTML。语法类似C#的预处理指令。
<!-- 仅当是开发构建时，才引入一个调试面板 --> #if DEVELOPMENT_PLAYER <div id="debug-panel" style="position: absolute; top: 10px; left: 10px; background: rgba(0,0,0,0.5); color: white; padding: 10px;"> 开发模式已启用 </div> #endif <!-- 根据是否使用WASM来加载不同的资源描述 --> #if USE_WASM <p>正在使用高性能的WebAssembly...</p> #else <p>正在使用兼容性模式(asm.js)...</p> #endif注意事项：条件指令中的表达式是JavaScript表达式，最终会被求值为
true或false。你可以使用&&,||,!等操作符，也可以引用预处理变量，例如#if TOTAL_MEMORY > 536870912（判断内存是否大于512MB）。
3.3 定义自定义模板变量：从编辑器传递参数到HTML
有时，你希望从Unity的Player Settings里直接控制HTML模板的某些属性，而不是每次去改HTML代码。这就需要“自定义模板变量”。
- 在模板中声明变量：在你的
index.html中，使用预处理语法{{{ MY_CUSTOM_VAR }}}定义一个位置。<meta name="description" content="{{{ PAGE_DESCRIPTION }}}"> - 触发Unity识别：确保这个变量名没有在模板的其他地方（如JavaScript代码里）被声明为局部变量。Unity的预处理器会扫描模板，将所有符合“在模板中使用但未在模板脚本中声明”的
{{{XXX}}}变量，识别为自定义变量。 - 在Unity编辑器中配置：完成一次构建（或仅仅保存项目设置）后，回到
Project Settings -> Player -> Resolution and Presentation。滚动到下方，你会看到一个名为**“WebGL Template Parameters”**的折叠区域（在旧版本中可能直接显示在模板选择下方）。Unity会自动在这里为PAGE_DESCRIPTION生成一个输入框。 - 填写并构建：在输入框中填入描述文本，例如“这是一个震撼的3D网页体验”。构建时，这个值就会替换掉
index.html中的{{{ PAGE_DESCRIPTION }}}。
避坑技巧：自定义变量名中的下划线
_在Unity编辑器界面中会显示为空格，以提高可读性。但你在模板中引用时，必须使用下划线。这是为了区分多个单词的变量，例如PAGE_TITLE。
4. 核心交互实现：Unity与JavaScript的双向通信
无缝集成的“灵魂”在于Unity内容能与包裹它的网页进行对话。这分为两个方向：从JavaScript调用Unity中的C#方法，以及从Unity C#调用网页中的JavaScript函数。
4.1 JavaScript调用C#：SendMessage与更优解
经典方法：GameObject.SendMessage这是最直接的方法。在网页的JavaScript中，你可以通过unityInstance对象调用SendMessage。
// 假设unityInstance是createUnityInstance返回的实例 unityInstance.SendMessage('MyGameObjectName', 'MyMethodName', 'argumentString');MyGameObjectName: Unity场景中某个GameObject的名字。MyMethodName: 挂在该GameObject上的脚本中的一个公有方法名。argumentString: 传递给方法的参数，只能是一个字符串。如果需要传复杂数据，需要序列化成JSON字符串。
C#脚本示例：
using UnityEngine; public class MessageReceiver : MonoBehaviour { // 这个方法将被JavaScript调用 public void MyMethodName(string argumentFromJS) { Debug.Log($"收到来自网页的消息: {argumentFromJS}"); // 可以解析JSON: MyData data = JsonUtility.FromJson<MyData>(argumentFromJS); } }常见问题：
SendMessage虽然简单，但效率不高，且依赖于GameObject名称（容易因重命名而失效）。它更适合简单的命令传递。
推荐方法：直接调用C#静态方法（Unity 2020.3+）更高效、更现代的方式是利用[DllImport("__Internal")]特性，将C#方法直接暴露给JavaScript。
在C#中声明外部方法：
using System.Runtime.InteropServices; using UnityEngine; public class JSBridge : MonoBehaviour { // 声明一个由外部（JavaScript）实现的函数 [DllImport("__Internal")] private static extern void JSCallToUnity(string message); // 供JavaScript调用的静态方法 [DllImport("__Internal")] public static extern void TriggerUnityEvent(string eventData); }注意，
JSCallToUnity的函数体在C#中是不存在的，它需要在JavaScript侧实现。而TriggerUnityEvent是我们要暴露给JS调用的。在JavaScript中实现C#声明的外部函数： 在
index.html的<script>标签或外部JS文件中，实现JSCallToUnity。// 这个函数名必须与C#中[DllImport]声明的一致 mergeInto(LibraryManager.library, { JSCallToUnity: function (messagePointer) { // 将指针转换为C#字符串 var message = UTF8ToString(messagePointer); console.log('JS收到来自C#的调用，消息:', message); // 这里可以触发网页上的其他操作 document.getElementById('status').innerText = message; } });mergeInto是Unity Emscripten工具链提供的特殊函数，用于将你的JavaScript函数注入到Unity的运行时库中。在JavaScript中调用C#静态方法： 现在，你可以直接调用
TriggerUnityEvent了。但注意，在WebGL中，暴露的C#方法会被添加一个_前缀，并且参数如果是字符串，需要特殊处理。// 错误方式：直接调用 // unityInstance.TriggerUnityEvent('hello'); // 这行不通 // 正确方式：通过unityInstance.Module调用，并使用字符串分配器 function callUnityStaticMethod() { const eventData = JSON.stringify({type: 'click', value: 100}); // 分配内存并写入字符串 const buffer = unityInstance.Module._malloc(eventData.length + 1); unityInstance.Module.stringToUTF8(eventData, buffer, eventData.length + 1); // 调用方法，注意方法名前有下划线 unityInstance.Module._TriggerUnityEvent(buffer); // 释放内存 unityInstance.Module._free(buffer); }这个过程比较繁琐。更实用的方法是：在C#端提供一个包装方法，接受普通字符串参数，内部处理指针转换，然后JavaScript通过
SendMessage调用这个包装方法。或者，使用我下面推荐的通用桥接类。
4.2 C#调用JavaScript：Application.ExternalEval与现代方法
传统方法（已过时）：Application.ExternalEval("alert('hi')");在较新Unity版本中可能无效或不推荐。
现代标准方法：JSLib插件这是官方推荐且最强大的方式。你需要创建一个.jslib文件。
- 创建
.jslib文件：在项目的Assets文件夹下（或任意Plugins子文件夹），创建一个文本文件，将其后缀改为.jslib，例如MyPlugin.jslib。 - 编写JSLib代码：
// MyPlugin.jslib mergeInto(LibraryManager.library, { // 定义一个名为ShowAlert的JS函数，供C#调用 ShowAlert: function (messagePointer) { var message = UTF8ToString(messagePointer); window.alert("来自Unity的提示: " + message); }, // 定义一个获取浏览器用户代理的函数 GetUserAgent: function () { var agent = navigator.userAgent; var buffer = _malloc(agent.length + 1); stringToUTF8(agent, buffer, agent.length + 1); return buffer; // 返回字符串指针给C# } }); - 在C#中声明并使用：
这种方式功能强大，可以定义复杂的交互逻辑和返回值处理。using System.Runtime.InteropServices; using UnityEngine; public class WebGLCommunicator : MonoBehaviour { // 声明对JSLib中函数的引用 [DllImport("__Internal")] private static extern void ShowAlert(string message); [DllImport("__Internal")] private static extern string GetUserAgent(); void Start() { // 调用JavaScript的alert ShowAlert("游戏加载完成！"); // 调用JS函数并获取返回值 string userAgent = GetUserAgent(); Debug.Log("浏览器信息: " + userAgent); } }
简化通信：封装一个通用桥接类在实际项目中，我通常会封装一个WebGLBridge单例类，统一管理所有与JS的通信，处理字符串编码/解码的细节，并提供更友好的API。
// WebGLBridge.cs using System.Runtime.InteropServices; using UnityEngine; public class WebGLBridge : MonoBehaviour { public static WebGLBridge Instance; void Awake() { Instance = this; } // 调用网页JS函数 public void CallJS(string funcName, params object[] args) { #if UNITY_WEBGL && !UNITY_EDITOR string jsonArgs = JsonUtility.ToJson(new JSArgs { data = args }); CallJS_Internal(funcName, jsonArgs); #else // 在编辑器中模拟调用，方便调试 Debug.Log($"[模拟JS调用] {funcName}({string.Join(", ", args)})"); #endif } [DllImport("__Internal")] private static extern void CallJS_Internal(string funcName, string jsonArgs); // 供JS调用的C#方法 public void OnJSMessage(string jsonMessage) { var msg = JsonUtility.FromJson<JSMessage>(jsonMessage); // 分发消息给其他游戏系统... Debug.Log($"收到JS消息: {msg.command}, 数据: {msg.data}"); } // 数据结构 [System.Serializable] private class JSArgs { public object[] data; } [System.Serializable] private class JSMessage { public string command; public string data; } }对应的JSLib部分实现CallJS_Internal，将JSON字符串解析并调用真正的全局JS函数。这样在C#中只需要WebGLBridge.Instance.CallJS("updateScore", 100);，清晰又安全。
5. 性能优化与问题排查实战
5.1 解决“初始化很久”与加载优化
用户搜索“unity webgl初始化很久”是高频痛点。优化加载体验是集成的重中之重。
1. 压缩与分包策略：
- 构建压缩：在
Player Settings -> Publishing Settings中，将Compression Format设置为Brotli。Brotli比Gzip压缩率更高，能显著减少网络传输体积。确保你的服务器支持并配置了Brotli压缩（如Nginx的brotli on指令）。 - 资源分包与按需加载：不要把所有资源打在一个巨大的
.data文件里。使用Unity的Addressable Asset System（可寻址资源系统）。将首包必需资源（启动场景、核心UI）标记为Local，将大型场景、高清纹理、不常用模型标记为Remote。这样，初始加载的.data文件会小很多，初始化速度自然加快。用户进入特定功能时，再异步加载远程资源包。
2. 自定义进度条与加载反馈： Unity默认的加载进度条信息有限。我们可以通过监听createUnityInstance的onProgress回调，实现更精细的加载反馈。
// 在自定义模板的index.html中 var config = { // ... 其他配置 }; var loadingBar = document.getElementById('custom-loading-bar'); var loadingText = document.getElementById('custom-loading-text'); createUnityInstance(canvas, config, function(progress) { // progress 是一个0到1之间的浮点数 var percentage = Math.round(progress * 100); loadingBar.style.width = percentage + '%'; loadingText.textContent = `加载中... ${percentage}%`; // 可以在这里根据progress值切换不同的提示文字 if (progress < 0.3) { loadingText.textContent = '正在初始化引擎...'; } else if (progress < 0.7) { loadingText.textContent = '正在加载资源...'; } else { loadingText.textContent = '即将完成...'; } }).then(function(unityInstance) { // 加载成功，隐藏加载界面 document.getElementById('loading-screen').style.display = 'none'; // 保存实例供后续使用 window.myUnityInstance = unityInstance; }).catch(function(message) { // 加载失败 console.error('Unity加载失败: ', message); loadingText.textContent = '加载失败，请刷新页面或检查网络。'; loadingText.style.color = 'red'; });通过自定义UI，你可以设计更美观、信息更丰富的加载体验，有效缓解用户等待的焦虑感。
3. 内存管理 (TOTAL_MEMORY)： 在Player Settings -> Configuration中设置的WebGL Memory Size，就是预处理变量{{{ TOTAL_MEMORY }}}。这个值不是越大越好。
- 设置过小：游戏容易因内存不足而崩溃，尤其在加载大量资源时。错误信息可能包含“out of memory”。
- 设置过大：浏览器在初始化WebGL上下文时需要预留连续的内存空间。过大的值可能导致初始化时间变长，甚至在内存紧张的设备上直接分配失败。
- 如何设定：在开发阶段，通过浏览器的开发者工具（如Chrome的
performance.memory）监控你的应用实际使用的堆内存峰值。将TOTAL_MEMORY设置为略高于这个峰值（例如增加20%-50%作为缓冲）。通常，对于中等复杂度的3D项目，256MB到512MB是一个合理的起始范围。对于2D或轻量项目，可以从128MB开始尝试。
5.2 常见问题排查速查表
| 问题现象 | 可能原因 | 排查步骤与解决方案 |
|---|---|---|
| 黑屏，控制台无错误 | 1. Canvas尺寸为0。 2. createUnityInstance调用失败但未捕获错误。3. 资源路径错误，文件404。 | 1. 检查CSS，确保#unity-canvas有明确的宽高。2. 用 .catch()捕获createUnityInstance的Promise错误并打印。3. 打开浏览器开发者工具“网络(Network)”标签，查看 .wasm,.data,.js等文件是否成功加载（状态码200）。检查config中的dataUrl,frameworkUrl路径是否正确。 |
| “A WebGL context could not be created” | 1. 浏览器不支持WebGL或已禁用。 2. 显卡驱动问题。 3. TOTAL_MEMORY设置过大，浏览器无法分配。 | 1. 访问webglreport.com检查支持情况。引导用户启用WebGL。2. 更新显卡驱动。 3. 在 index.html加载前检测WEBGL.support，给出友好提示。4. 尝试减小 TOTAL_MEMORY。 |
| 纹理/材质变紫 | 着色器编译失败或纹理未加载。在WebGL中，Unity的着色器需要被翻译成GLSL ES。 | 1. 检查控制台是否有着色器编译错误。 2.确保所有自定义Shader兼容WebGL。避免使用Surface Shader中不支持的复杂节点。使用 Shader.Find时做好空值检查。3. 如果是Addressable资源变紫，检查打包和加载路径，确保依赖的Shader Variant Collection也被正确打包。 |
| 与HTML UI元素点击冲突 | Canvas覆盖了整个页面或层级过高，拦截了鼠标事件。 | 1. 调整Canvas的CSSz-index，确保它只在需要时位于顶层。2. 或者，在Unity中处理射线投射时，可以通过 EventSystem.current.IsPointerOverGameObject()判断是否点击在了UI上，避免与网页UI冲突。 |
| 移动端触摸失灵或卡顿 | 1. 未处理触摸事件。 2. 性能问题。 | 1. 在index.html的<meta>标签中确保有viewport设置，并检查Unity Input设置中触摸是否启用。2. 针对移动端大幅降低画质（分辨率缩放、关闭抗锯齿、简化Shader）。使用 Application.targetFrameRate限制帧率以节省电量。 |
| 发布后资源丢失（Use Existing Build模式） | 在Unity编辑器中切换场景或资源后，直接使用旧的构建文件夹运行，新内容未包含在内。 | “Use Existing Build”模式仅用于快速测试构建流程，不会重新打包资源。任何资源或代码变更后，都必须重新构建(Build)。这是新手常踩的坑。 |
5.3 调试技巧：在浏览器中调试C#代码
很多人不知道，Unity WebGL是支持在浏览器中调试C#源码的。
- 开启开发构建与调试符号：在构建时，勾选
Development Build和Script Debugging。在Publishing Settings中，可以勾选Debugging下的选项以生成更详细的符号。 - 使用兼容性更好的浏览器：Chrome和Edge的开发者工具对WebAssembly调试支持较好。
- 启动调试：构建并运行后，打开浏览器开发者工具，找到“源代码(Sources)”标签。你应该能看到一个类似
file://的虚拟目录，展开后可能看到UnityLoader.js和你的项目文件夹。如果符号加载正确，你甚至能看到你的C#脚本文件，并可以设置断点、单步调试。 - 查看Console：Unity的
Debug.Log输出会重定向到浏览器的JavaScript控制台。你可以在这里看到所有的日志、警告和错误信息。使用Debug.LogError和Debug.LogWarning可以让信息更醒目。
6. 进阶集成：多实例、响应式与部署
6.1 实现响应式布局
默认模板的Canvas宽高是固定的。要让Unity内容适应不同屏幕，需要在HTML/CSS和Unity内共同处理。
HTML/CSS侧：
<style> #unity-container { position: relative; width: 100vw; /* 视口宽度 */ height: 100vh; /* 视口高度 */ overflow: hidden; display: flex; justify-content: center; align-items: center; background: #000; } #unity-canvas { width: 100%; height: 100%; /* 保持内容比例，类似 background-size: contain */ object-fit: contain; } /* 或者选择 cover 模式，填满但可能裁剪 */ /* object-fit: cover; */ </style> ... <div id="unity-container"> <canvas id="unity-canvas" tabindex="-1"></canvas> </div>Unity C#侧：你需要监听屏幕尺寸变化，并调整相机或UI。
using UnityEngine; public class ResponsiveHandler : MonoBehaviour { private int lastScreenWidth; private int lastScreenHeight; void Start() { UpdateResponsive(); lastScreenWidth = Screen.width; lastScreenHeight = Screen.height; } void Update() { if (Screen.width != lastScreenWidth || Screen.height != lastScreenHeight) { UpdateResponsive(); lastScreenWidth = Screen.width; lastScreenHeight = Screen.height; } } void UpdateResponsive() { float screenRatio = (float)Screen.width / Screen.height; float targetRatio = 16f / 9f; // 你的设计宽高比 // 示例：调整相机视口 Camera mainCam = Camera.main; if (mainCam != null) { if (screenRatio >= targetRatio) { // 屏幕更宽，上下留黑边（Letterbox） float normalizedHeight = targetRatio / screenRatio; mainCam.rect = new Rect(0, (1 - normalizedHeight) / 2, 1, normalizedHeight); } else { // 屏幕更高，左右留黑边（Pillarbox） float normalizedWidth = screenRatio / targetRatio; mainCam.rect = new Rect((1 - normalizedWidth) / 2, 0, normalizedWidth, 1); } } // 同时，也需要调整你的UI锚点或布局来适应新的安全区域 } }6.2 部署注意事项：服务器配置
将构建好的文件扔到服务器上，有时访问还是白屏，这通常是服务器MIME类型配置问题。
- .wasm 文件：必须配置正确的MIME类型
application/wasm。对于Nginx，在配置文件中添加：location ~ \.wasm$ { add_header Content-Type application/wasm; } - .data 和 .js.br/.wasm.br 文件：如果使用了Brotli压缩，服务器需要配置对
.br后缀的文件返回正确的Content-Encoding: br头。同时，.data文件可能很大，确保服务器支持分块传输（Transfer-Encoding: chunked）和断点续传（Accept-Ranges: bytes）。 - 跨域问题 (CORS)：如果你的HTML页面和构建资源文件（.data, .wasm等）不在同一个域名/端口下，浏览器会因为同源策略阻止加载。需要在资源服务器上设置CORS头，例如
Access-Control-Allow-Origin: *（生产环境应指定具体域名）。
6.3 版本更新与缓存策略
WebGL应用资源较大，浏览器缓存能极大提升重复访问速度，但也会导致用户无法获取新版本。
解决方案：在构建时，使用哈希文件名。在Unity的Player Settings -> Publishing Settings中，勾选Append Hash To WebGL Builds。这样构建出的文件名会带有内容哈希值（如mygame.abcd1234.wasm）。每次内容变化，哈希值变，文件名就变，浏览器会将其视为新文件重新下载。而HTML文件（或入口JS）可以设置较短的缓存时间或不缓存，让它总能获取到最新的资源文件列表。
在自定义模板中，你不再需要手动写死{{{ DATA_FILENAME }}}这样的变量，因为Unity的预处理会自动替换为带哈希的实际文件名。你只需要确保你的服务器能正确提供这些动态名称的文件即可。
