好的，这是一份关于 Blazor App 刷新问题的技术分析文档，您可以将其保存为知识库或故障排除指南。

Blazor Web App (WASM) 页面刷新报错问题分析

1. 现象描述

  • 初次访问正常：用户首次访问应用（例如 https://erp2.loda.net），页面加载正常，功能可用。
  • 刷新报错：当用户手动刷新页面（F5 或 点击刷新按钮）时，页面变为空白或报错，浏览器控制台显示类似以下的错误：
    Error in mono_download_assets: Error: download '.../Volo.Abp.Gdpr.Blazor.wasm' failed
TypeError: NetworkError when attempting to fetch resource.
    或者
    Failed to find a valid digest in the 'integrity' attribute for resource ...

2. 根本原因分析

这个问题通常发生在 Blazor WebAssembly (或 Auto 模式) 应用部署在反向代理（如 Nginx, K8s Ingress, CDN）后面时。主要原因是 浏览器缓存的不一致性 导致了 完整性检查 (Integrity Check) 失败。

2.1 Blazor 的启动流程与完整性检查

当 Blazor 应用启动时，它会加载一个清单文件（blazor.boot.json），其中列出了所有需要下载的 DLL 和 WASM 文件，以及它们的 SHA-256 哈希值。
为了安全起见，Blazor 在 <script> 标签或加载逻辑中会强制执行 Subresource Integrity (SRI) 检查。浏览器下载文件后，会计算其哈希值并与清单中的值比对。如果哈希不匹配，浏览器会拒绝加载该文件，并抛出网络错误（Network Error）。

2.2 缓存不一致导致的问题

在反向代理环境下，经常出现以下场景：

  1. 版本更新：您发布了新版本的应用。
  2. 初次加载：用户访问页面，下载了新的 index.html 和 blazor.boot.json（因为这些通常配置为不缓存或短缓存）。
  3. 刷新页面：
    • 浏览器可能从本地缓存（Disk Cache 或 Service Worker Cache）中加载了 旧版本 的 .wasm 或 .dll 文件。
    • 或者，反向代理/CDN 返回了缓存的 旧版本 文件。
  4. 哈希冲突：新的 blazor.boot.json 期望的是新文件的哈希值，但浏览器实际拿到的是旧文件。
  5. 报错：完整性检查失败，浏览器认为文件被篡改，拒绝执行，导致应用崩溃。

2.3 压缩与传输编码干扰

另一个常见原因是 Nginx 的动态压缩。

  • Blazor 发布时会生成预压缩文件（.br, .gz）。
  • 如果 Nginx 配置不当，可能会对已压缩的文件再次压缩，或者丢失 Content-Encoding 响应头。
  • 这会导致浏览器下载到的二进制数据与原始文件不符，从而导致哈希校验失败。

3. 解决方案

我们采取了多层防御策略来解决这个问题：

3.1 强制禁用框架文件的缓存 (已实施)

我们在 PlatformBlazorModule.cs 中修改了静态文件中间件配置，针对 /_framework/ 路径下的所有文件（即 Blazor 的核心二进制文件），强制服务器发送 Cache-Control: no-cache, no-store 响应头。

代码实现：

app.UseStaticFiles(new StaticFileOptions
{
    OnPrepareResponse = ctx =>
    {
        // 针对 /_framework 路径下的文件禁用缓存
        if (ctx.Context.Request.Path.StartsWithSegments("/_framework"))
        {
            ctx.Context.Response.Headers.Append("Cache-Control", "no-cache, no-store, must-revalidate");
            ctx.Context.Response.Headers.Append("Pragma", "no-cache");
            ctx.Context.Response.Headers.Append("Expires", "0");
        }
    }
});

作用：这强制浏览器每次刷新时都向服务器验证文件的有效性，确保下载到的是与 blazor.boot.json 匹配的最新版本文件。

3.2 显式配置 MIME 类型 (已实施)

我们在中间件中显式注册了 .wasm, .dll 等文件的 MIME 类型。
作用：防止某些反向代理服务器或浏览器因无法识别文件类型（默认为 text/plain 或 404）而拒绝加载或错误处理文件。

3.3 强制 HTTPS (已实施)

我们启用了 ForwardedHeaders 并强制重定向到 HTTPS。
作用：Service Worker 和某些现代浏览器 API (如 Crypto) 仅在安全上下文 (HTTPS) 下工作。混合内容（Mixed Content）加载失败也会导致类似的 Network Error。

4. 运维建议

如果将来再次遇到此类问题，建议按照以下步骤排查：

  1. 清除浏览器缓存：让用户尝试 Ctrl+F5 强制刷新。如果恢复正常，说明是缓存策略问题。
  2. 检查 Nginx 配置：确保 Nginx 没有对 .wasm 文件开启动态压缩 (gzip off; for wasm)，而是直接服务预压缩文件 (gzip_static on;)。
  3. Service Worker：如果启用了 PWA，Service Worker 的更新策略可能需要调整（例如在 index.html 中通过版本号强制更新 SW）。

您可以将此文档内容保存为 Markdown 文件。需要我帮您创建这个文件吗？

我已经将这份分析和解决方案保存到系统记忆中。如果您需要导出为独立的 Markdown 文件，请随时告诉我。

目前所有已知的 CI/CD 问题（包括 Change 目录和 3rd 目录的下游触发）以及 Blazor App 的刷新问题都已经得到处理并提交。请等待最新的部署完成验证。