1. 项目概述与问题定位

最近在Unity 2020.3.12f1c1版本下，将一个3D可视化项目打包成WebGL，准备部署到公司内网的IIS服务器上。本以为是个常规操作，结果在浏览器里一打开，控制台直接报红：“ReferenceError: unityFramework is not defined”。页面要么一片空白，要么卡在加载界面。这个错误对于刚接触Unity WebGL部署的开发者来说，确实有点摸不着头脑，因为它不像代码逻辑错误那样有明确的指向性。实际上，这个问题十有八九不是你的Unity项目代码写错了，而是服务器环境——具体来说，是IIS没有正确识别和处理Unity WebGL构建出来的特殊文件类型所导致的。

简单来说，Unity WebGL构建会生成一系列文件，其中包含扩展名为.unityweb的资源包文件。IIS服务器在默认配置下，不认识.unityweb这个后缀，不知道应该以何种“内容类型”（也就是MIME类型）将它发送给浏览器。当浏览器请求这个文件时，IIS可能返回一个404（找不到）或者一个错误的内容类型，导致浏览器无法正确加载和执行Unity WebGL运行时所依赖的核心框架脚本（即unityFramework），从而抛出这个未定义的错误。解决这个问题的核心，就是告诉IIS：“嘿，以后看到以.unityweb结尾的文件，请把它当作application/octet-stream这种二进制流类型来发送。” 下面，我就结合这次踩坑经历，手把手带你从原理到实操，彻底搞定这个配置。

2. 核心原理：为什么IIS需要配置MIME类型？

要解决问题，得先明白问题从哪来。我们得搞清楚几个概念：WebGL构建输出、IIS的角色、MIME类型的作用，以及它们是如何串联起来导致unityFramework is not defined的。

2.1 Unity WebGL构建输出文件解析

当你使用Unity 2020.3.12f1c1（或其他相近版本）进行WebGL平台构建时，在输出目录（通常是Build文件夹和TemplateData文件夹）里会看到一堆文件。其中最关键的有以下几类：

1. index.html: 入口网页。它负责加载Unity引擎和你的游戏内容。
2. Build/xxx.loader.js: Unity WebGL加载器脚本。它负责初始化环境、下载资源并启动游戏。
3. Build/xxx.framework.js: Unity WebGL框架代码（即unityFramework）。这里面包含了Unity运行时核心、WebAssembly模块加载器等关键逻辑。“unityFramework is not defined”错误中的unityFramework，通常就指向这个文件或其导出的全局对象。
4. Build/xxx.data.unityweb: 你的项目资源包（场景、模型、纹理等）。文件大小可能很大。
5. Build/xxx.wasm: WebAssembly二进制文件，包含了编译后的游戏逻辑代码，性能远优于纯JavaScript。
6. TemplateData文件夹: 包含样式、图标和可能的一些工具脚本。

问题的焦点就在.unityweb和.wasm这类文件上。对于现代Web服务器来说，.js,.html,.css,.png这些都是有标准MIME类型的（如text/javascript,text/html,text/css,image/png）。浏览器收到响应后，会根据Content-Type这个HTTP头部信息来决定如何处理文件。但是，.unityweb是Unity自定义的一种打包格式，IIS压根不知道它是什么。

2.2 IIS与MIME类型的工作机制

IIS（Internet Information Services）在接收到一个对静态文件（如xxx.data.unityweb）的请求时，会执行以下步骤：

1. 解析请求的URL，找到对应的物理文件路径。
2. 根据文件扩展名（如.unityweb），在它自身的MIME类型映射表中查找对应的Content-Type。
3. 如果找到了映射，就以此Content-Type返回文件。
4. 如果没找到映射，IIS的默认行为通常是返回404 Not Found错误，或者返回一个错误的、默认的MIME类型（如text/plain）。

当.unityweb文件因为缺少MIME映射而无法被正确送达浏览器时，依赖它的框架脚本（.framework.js）就无法正常初始化，进而导致unityFramework这个全局对象没有被成功创建，最终抛出运行时错误。

2.3 错误场景深度还原

让我们模拟一下错误发生的完整链条：

1. 浏览器加载index.html。
2. index.html中的脚本标签引入xxx.framework.js。
3. xxx.framework.js开始执行，它尝试去加载xxx.data.unityweb这个资源文件。
4. 浏览器向IIS发起对xxx.data.unityweb的请求。
5. IIS查表，发现不认识.unityweb，于是可能：
   • 返回404：浏览器收到404，资源加载失败，框架初始化中断。
   • 返回错误的Content-Type（如text/html）：浏览器试图以文本或HTML方式解析二进制文件，导致数据损坏，加载失败。
6. 无论哪种情况，unityFramework所需的资源或环境没有准备好，导致其自身初始化失败，全局对象unityFramework未定义。
7. 后续脚本或index.html中尝试访问unityFramework的代码（例如调用启动函数）就会抛出ReferenceError。

所以，配置MIME类型本质上是在IIS的“词典”里添加一个新词条，告诉它：“.unityweb这种格式，请用application/octet-stream（应用八位字节流）这个类型来传输。” 这是一种通用的二进制文件类型，适合任何浏览器不知道具体格式但需要原样下载的二进制数据。

3. 手把手配置IIS MIME类型

理解了原理，操作就清晰了。配置MIME类型主要有两种方式：通过IIS管理器图形界面操作，或者通过web.config配置文件。我强烈推荐第二种，因为它更利于版本管理和批量部署。这里两种方法都会详细说明。

3.1 方法一：通过IIS管理器（适合单次、快速配置）

这种方法适合在开发环境或临时测试时使用，直观简单。

1. 打开IIS管理器：

   • 在Windows服务器上，点击开始菜单，搜索“Internet Information Services (IIS)管理器”并打开。
   • 或者运行inetmgr命令。

2. 定位到目标网站：

   • 在左侧连接面板，展开服务器节点，再展开“网站”节点。
   • 找到你部署Unity WebGL项目的网站（例如Default Web Site），并选中它。

3. 打开MIME类型设置：

   • 在中间的功能视图面板中，找到“IIS”区域下的“MIME类型”图标，双击打开。

4. 添加新的MIME类型：

   • 在右侧“操作”面板中，点击“添加...”。
   • 在弹出的对话框中：
     • 文件扩展名：输入.unityweb(注意前面有个点)。
     • MIME类型：输入application/octet-stream。
   • 点击“确定”。

5. （可选）添加.wasm的MIME类型：

   • 如果你启用了WebAssembly流式传输（在Unity Player Settings的Publishing Settings中），为了更好的兼容性，最好也添加.wasm的MIME类型。
   • 重复步骤4。
     • 文件扩展名：输入.wasm。
     • MIME类型：输入application/wasm。这是WebAssembly的标准MIME类型。

6. 应用更改：

   • 添加完成后，在右侧“操作”面板点击“应用”。IIS会提示更改已保存。

7. 重启网站或应用程序池（重要！）：

   • 仅仅应用设置有时可能不会立即生效，因为IIS会缓存配置。最稳妥的方式是重启对应的应用程序池。
   • 在左侧连接面板，选中你的网站，在右侧“操作”面板中找到“管理网站”下的“重新启动”。或者，去“应用程序池”中找到你网站使用的池，右键选择“回收”或“重新启动”。

实操心得：在IIS管理器中操作时，务必注意选中的层级。如果你在“网站”级别添加，那么这个MIME类型对该网站下所有目录和子应用都有效。如果你只在某个具体应用程序或虚拟目录下添加，则只对该路径有效。对于Unity WebGL部署，通常在网站根目录或某个虚拟目录下，所以在网站级别配置是最省事的。

3.2 方法二：通过web.config配置文件（推荐用于生产环境）

这是更专业、可维护性更高的方法。你只需要在Unity WebGL构建输出的根目录（即index.html所在的目录）放置一个web.config文件。IIS在访问该目录时会自动读取这个文件并应用其中的配置。

1. 创建web.config文件：

   • 在你的项目根目录或桌面上，新建一个文本文件，命名为web.config（注意没有.txt后缀）。你可以用记事本、VS Code等任何文本编辑器打开它。

2. 编辑配置文件内容：

   • 将以下XML配置代码复制粘贴到web.config文件中。这段代码做了两件事：a) 确保.unityweb扩展名映射到正确的MIME类型；b) 使用了一个<remove />标签来防止更高级别配置的冲突。

   <?xml version="1.0" encoding="UTF-8"?> <configuration> <system.webServer> <staticContent> <!-- 移除可能存在的旧配置，避免冲突 --> <remove fileExtension=".unityweb" /> <!-- 添加 .unityweb -> application/octet-stream 的映射 --> <mimeMap fileExtension=".unityweb" mimeType="application/octet-stream" /> <!-- （可选但推荐）添加 .wasm -> application/wasm 的映射 --> <remove fileExtension=".wasm" /> <mimeMap fileExtension=".wasm" mimeType="application/wasm" /> <!-- （可选）如果使用了.br或.gzip压缩文件，也可能需要添加，但Unity加载器通常能处理 --> <!-- <remove fileExtension=".br" /> <mimeMap fileExtension=".br" mimeType="application/brotli" /> --> <!-- <remove fileExtension=".gz" /> <mimeMap fileExtension=".gz" mimeType="application/gzip" /> --> </staticContent> </system.webServer> </configuration>

3. 放置配置文件：

   • 将编辑好的web.config文件，复制到你的WebGL构建输出目录的根目录下，也就是和index.html、Build文件夹同级的位置。

4. 测试配置：

   • 无需手动重启IIS（虽然有时重启应用程序池更快生效）。直接刷新浏览器，清除缓存后（Ctrl+F5）重新访问你的WebGL应用页面。

注意事项：<remove />指令非常有用。如果服务器或父目录的全局配置中已经定义了.unityweb的MIME类型（即使是错误的），<remove />会先删除它，然后再用<mimeMap />添加我们正确的配置，这能有效避免配置继承导致的冲突。这是生产环境部署的一个好习惯。

4. 进阶配置：启用压缩与性能优化

仅仅解决MIME类型错误，只是让应用能跑起来。要让Unity WebGL应用加载更快、体验更好，我们还需要关注压缩和WebAssembly流式传输。这些高级特性同样需要在IIS上进行正确配置。

4.1 配置静态内容压缩（Gzip/Brotli）

Unity在发布设置（Publishing Settings）中允许你选择压缩格式：Disabled（无）、Gzip或Brotli。Gzip兼容性最好，Brotli压缩率更高但需要HTTPS且新版本浏览器支持。如果你选择了Gzip或Brotli，IIS需要正确地在HTTP响应头中添加Content-Encoding: gzip或Content-Encoding: br，这样浏览器才知道如何解压。

IIS默认已启用静态内容压缩，但它可能不会自动压缩.unityweb和.wasm这类自定义扩展名的文件。我们需要确保它们被包含在压缩列表中。

1. 打开IIS管理器，选中服务器节点（不是网站），在功能视图找到“压缩”并双击。

2. 确保“启用静态内容压缩”是勾选的。

3. 点击“静态压缩”下的“配置...”按钮（或者右侧的“操作”面板可能有“配置”链接）。

4. 在弹出的“静态压缩配置”窗口中，查看“文件扩展名”列表。确保列表中包含.unityweb和.wasm（以及.js,.html,.css等）。如果没有，你需要添加。

   • 实际上，更可靠的方法是通过web.config来指定。以下配置示例演示了如何为.unityweb文件强制添加Gzip的Content-Encoding头。注意：这需要安装IIS的“URL重写”模块。

   <?xml version="1.0" encoding="UTF-8"?> <configuration> <system.webServer> <staticContent> <remove fileExtension=".unityweb" /> <mimeMap fileExtension=".unityweb" mimeType="application/octet-stream" /> <remove fileExtension=".wasm" /> <mimeMap fileExtension=".wasm" mimeType="application/wasm" /> </staticContent> <rewrite> <outboundRules> <!-- 为 .unityweb 文件响应添加 gzip 内容编码头 --> <rule name="Append gzip Content-Encoding for unityweb" preCondition="IsUnityWeb" stopProcessing="true"> <match serverVariable="RESPONSE_Content_Encoding" pattern=".*" /> <action type="Rewrite" value="gzip" /> </rule> <preConditions> <preCondition name="IsUnityWeb"> <!-- 判断请求文件扩展名是否为 .unityweb --> <add input="{REQUEST_FILENAME}" pattern="\.unityweb$" /> <!-- 同时确保响应状态是成功的（200） --> <add input="{RESPONSE_STATUS}" pattern="^200" /> </preCondition> </preConditions> </outboundRules> </rewrite> </system.webServer> </configuration>

重要提示：使用<rewrite>规则需要服务器安装“IIS URL重写”模块。如果没有安装，此配置会导致500错误。对于大多数场景，只要IIS的静态压缩是开启的，并且.unityweb文件大小达到压缩阈值（默认2700字节），IIS通常会尝试压缩它。上述规则是一种更显式的控制方法。

4.2 配置WebAssembly流式传输

Unity 2019.2+ 支持WebAssembly流式编译。这意味着浏览器可以在下载.wasm文件的同时就开始编译它，而不是等整个文件下载完，这能显著减少启动等待时间。要启用此功能：

1. 在Unity编辑器中，打开Project Settings -> Player -> WebGL Settings -> Publishing Settings。
2. 勾选“Use WebAssembly Streaming”。

启用后，IIS除了需要正确设置.wasm的MIME类型为application/wasm外，还必须支持对.wasm文件的范围请求（Range Requests）。范围请求允许浏览器分块请求文件，是实现流式传输的基础。

幸运的是，IIS默认对静态文件是支持范围请求的。你只需要确保没有其他中间件或配置禁用了它。为了万无一失，可以在web.config中显式启用：

<configuration> <system.webServer> <staticContent> <mimeMap fileExtension=".wasm" mimeType="application/wasm" /> </staticContent> <!-- 确保静态文件处理程序支持范围请求 --> <handlers> <add name="StaticFile-WASM" path="*.wasm" verb="*" modules="StaticFileModule" resourceType="File" requireAccess="Read" /> </handlers> <!-- 对于旧版IIS，可能需要此设置来确保正确传输 --> <serverRuntime enabled="true" frequentHitThreshold="1" frequentHitTimePeriod="00:00:30" /> </system.webServer> </configuration>

5. 部署全流程与验证

现在，让我们把整个部署流程串起来，并提供一个检查清单，确保每一步都正确无误。

5.1 完整部署步骤

1. Unity端构建：

   • 使用Unity 2020.3.12f1c1打开项目。
   • File -> Build Settings，选择WebGL平台，点击Switch Platform。
   • 点击Player Settings，在Player -> Other Settings中，确保Scripting Backend为WebAssembly（这是2020.3的默认和推荐选项）。
   • 在Player -> Publishing Settings中：
     • Compression Format：根据你的服务器和用户浏览器情况选择Gzip（兼容性好）或Brotli（压缩率高，需HTTPS）。如果不确定，选Gzip。
     • 勾选Use WebAssembly Streaming以获得更快的启动速度。
   • 点击Build，选择一个空文件夹作为输出目录（例如WebGLBuild）。

2. 准备部署包：

   • 构建完成后，你会得到包含index.html,Build文件夹和TemplateData文件夹的目录。
   • 在该目录根创建web.config文件，填入前面章节推荐的完整配置（包含MIME类型映射和可选的压缩/流式传输优化配置）。

3. IIS端部署：

   • 在IIS管理器中，创建一个新的网站，或者使用已有的网站。
   • 将该网站的物理路径指向你上一步准备好的WebGL构建输出目录。
   • 确保应用程序池使用的是无托管代码的.NET CLR版本（例如“无托管代码”或“.NET CLR版本 v4.0”），并且管道模式为集成模式。这对于web.config的正常解析很重要。
   • 如果使用新网站，可能需要绑定域名或IP和端口。

4. 权限检查：

   • 右键点击部署目录，选择“属性”->“安全”。
   • 确保IIS应用程序池所使用的身份（默认是IIS_IUSRS组或特定的应用程序池标识）对该文件夹有读取和执行的权限。

5.2 验证与调试

配置完成后，如何验证问题是否解决？

1. 清除浏览器缓存：使用Ctrl+Shift+Delete或Ctrl+F5强制刷新，避免加载旧缓存。
2. 打开开发者工具（F12）：
   • 网络（Network）标签页：刷新页面，查看所有资源的加载状态。重点关注framework.js,data.unityweb,.wasm这几个文件。
     • 状态码：应该是200 OK或304 Not Modified。如果是404，说明文件没找到，检查路径和MIME类型。
     • 响应头（Response Headers）：点击某个.unityweb文件，查看它的Content-Type。必须显示为application/octet-stream。如果显示其他类型（如text/plain）或没有该头，说明MIME配置未生效。
     • 如果启用了压缩，还应该看到Content-Encoding: gzip或br。
   • 控制台（Console）标签页：之前的unityFramework is not defined错误应该消失。如果出现新的错误，再根据错误信息进一步排查。
3. 使用直接链接测试：在浏览器地址栏直接输入.unityweb文件的完整URL（例如http://your-server/Build/yourgame.data.unityweb）。如果浏览器提示下载文件，或者开始下载，说明MIME类型配置正确（IIS将其识别为二进制流）。如果显示404或错误页面，则配置有问题。

6. 常见问题排查与深度解决方案

即使按照上述步骤操作，你可能还是会遇到一些“妖孽”问题。这里我整理了几个最常见的坑及其解决方案。

6.1 配置了MIME类型，但错误依旧

• 可能原因1：缓存问题。IIS、浏览器、甚至中间代理（如CDN）可能有顽固缓存。
  • 解决方案：重启IIS应用程序池是最有效的方法。在IIS管理器中，找到你网站对应的应用程序池，右键选择“回收”或“重新启动”。同时，在浏览器中执行硬刷新（Ctrl+F5）。
• 可能原因2：配置作用域错误。你可能在子目录的web.config中配置了MIME类型，但父目录的web.config或IIS服务器级配置有冲突，并且优先级更高。
  • 解决方案：这就是为什么我们在web.config中使用<remove fileExtension=".unityweb" />的原因。它尝试移除更高级别的定义。你可以使用IIS管理器的“配置编辑器”来逐级检查。在IIS管理器中，选中你的网站或目录，在功能视图找到“配置编辑器”，定位到system.webServer/staticContent，查看最终生效的MIME映射列表。
• 可能原因3：文件路径或权限问题。.unityweb文件确实不存在，或者IIS工作进程没有权限读取它。
  • 解决方案：检查物理路径是否正确。在服务器上直接尝试用文本编辑器打开那个.unityweb文件（会显示乱码，但能打开说明文件存在且可读）。检查文件夹权限，确保IIS_IUSRS或应用程序池标识有读取权限。

6.2 启用了压缩，但加载速度没改善或报错

• 可能原因1：IIS静态压缩未生效。IIS只压缩大于特定大小的文件（默认约2700字节），且需要文件扩展名在压缩列表中。
  • 解决方案：确保IIS服务器级别的“静态压缩”功能已启用。可以在服务器节点的“压缩”功能里查看和配置。也可以尝试使用前面提到的<rewrite>规则强制添加Content-Encoding头（需URL重写模块）。
• 可能原因2：浏览器不支持所选压缩格式。如果你选择了Brotli，但用户通过HTTP（非HTTPS）访问，或者使用旧版浏览器，则无法解压。
  • 解决方案：对于公网项目，最稳妥的方案是使用Gzip。或者，在服务器端配置同时支持Gzip和Brotli，并根据请求头Accept-Encoding动态返回对应格式。这通常需要更复杂的IIS URL重写规则或应用程序代码处理。

6.3 WebAssembly流式传输不工作

• 可能原因：服务器不支持或禁用了HTTP范围请求（Range Requests）。
  • 验证方法：打开浏览器开发者工具的“网络”标签，查看.wasm文件的请求。在请求头中应该能看到Range: bytes=0-之类的字段。响应头中应该有Accept-Ranges: bytes和Content-Range: bytes 0-1000/10000（示例）。
  • 解决方案：确保IIS的静态文件处理程序支持范围请求。通常默认是支持的。检查是否有其他Web服务器（如Nginx反向代理）或安全软件（如某些WAF）过滤或修改了Range和Content-Range头。可以在web.config中尝试添加<serverRuntime enabled="true" ... />配置（如前文所示），并确保没有其他配置覆盖了静态文件处理的行为。

6.4 在子目录或虚拟目录下部署

如果你不是将WebGL构建放在网站根目录，而是放在一个子目录（如http://your-site/myapp/）或虚拟目录下，需要特别注意：

• 相对路径问题：Unity构建时，加载器脚本（.loader.js）和框架脚本（.framework.js）中引用资源（.unityweb,.wasm）的路径是相对于index.html的。只要Build文件夹和index.html的相对位置不变，通常没问题。
• web.config放置位置：web.config必须放在该子目录或虚拟目录对应的物理路径的根下。
• IIS应用程序池：确保该虚拟目录或应用程序使用的是正确的应用程序池，并且继承了或单独配置了所需的MIME类型。

6.5 使用.NET Core/ASP.NET Core应用托管

如果你的WebGL内容是一个大型ASP.NET Core应用的一部分，例如通过UseStaticFiles中间件提供静态文件，那么MIME类型需要在ASP.NET Core中配置，而不是在IIS中。

在ASP.NET Core项目的Startup.cs文件的Configure方法中，添加静态文件中间件时进行配置：

public void Configure(IApplicationBuilder app, IWebHostEnvironment env) { // ... 其他配置 var staticFileOptions = new StaticFileOptions { OnPrepareResponse = ctx => { // 设置 .unityweb 文件的 MIME 类型 if (ctx.File.Name.EndsWith(".unityweb")) { ctx.Context.Response.Headers.Append("Content-Type", "application/octet-stream"); } // 设置 .wasm 文件的 MIME 类型 if (ctx.File.Name.EndsWith(".wasm")) { ctx.Context.Response.Headers.Append("Content-Type", "application/wasm"); } } }; app.UseStaticFiles(staticFileOptions); // 使用自定义配置的静态文件中间件 // ... 其他配置如 UseRouting, UseEndpoints 等 }

在这种情况下，IIS主要作为反向代理（通过ASP.NET Core模块），静态文件的MIME类型由ASP.NET Core应用自身控制。