Blazor WASM DLL缓存自动更新失效问题排查及强制更新方案咨询

1. 问题可能的原因 #

• Service Worker 休眠或未触发更新：长期未访问应用的用户，浏览器会终止闲置的Service Worker进程。再次访问时，浏览器可能复用旧的Service Worker实例，该实例未同步最新的blazor.boot.json哈希映射，导致继续加载旧缓存的DLL。
• Service Worker 缓存了旧的 boot 文件：即使后端的blazor.boot.json已更新，若Service Worker自身缓存了旧版本的该文件，仍会基于旧哈希去加载DLL。
• 默认缓存逻辑的边缘场景：Blazor WASM默认的Service Worker缓存逻辑中，若部分DLL的哈希变更未被正确识别，或缓存键未与哈希强绑定，会导致旧DLL无法被自动替换。
• 浏览器缓存干扰：部分浏览器的严格缓存策略、隐私模式或第三方扩展（如广告拦截器）可能阻断新DLL的下载流程，保留旧缓存资源。

2. 代码/配置解决方案 #

2.1 优化Azure App Service缓存策略 #

通过配置缓存头，确保blazor.boot.json仅短时间缓存，带哈希的DLL可长期缓存（哈希变更会生成新文件名，无冲突风险）。

Windows App Service（web.config）

在项目根目录添加/修改web.config：

<?xml version="1.0" encoding="utf-8"?>
<configuration>
  <location path="blazor.boot.json">
    <system.webServer>
      <staticContent>
        <!-- 设置5分钟缓存，确保及时获取新版本 -->
        <clientCache cacheControlMode="UseMaxAge" cacheControlMaxAge="00:05:00" />
      </staticContent>
    </system.webServer>
  </location>
  <location path="_framework">
    <system.webServer>
      <staticContent>
        <!-- 带哈希的DLL/资源设置1年长期缓存 -->
        <clientCache cacheControlMode="UseMaxAge" cacheControlMaxAge="365.00:00:00" />
      </staticContent>
    </system.webServer>
  </location>
</configuration>

Linux/Static Web Apps（staticwebapp.config.json）

{
  "responseOverrides": {
    "blazor.boot.json": {
      "headers": {
        "cache-control": "public, max-age=300"
      }
    },
    "_framework/*.dll": {
      "headers": {
        "cache-control": "public, max-age=31536000"
      }
    }
  }
}

2.2 强制Service Worker主动检查更新 #

在应用启动时主动触发Service Worker更新检查，避免依赖浏览器默认机制。

Program.cs 配置

using Microsoft.AspNetCore.Components.WebAssembly.Hosting;

var builder = WebAssemblyHostBuilder.CreateDefault(args);
builder.RootComponents.Add<App>("#app");
builder.RootComponents.Add<HeadOutlet>("head::after");

// 注册Service Worker服务
builder.Services.AddBlazorWebAssemblyServiceWorker();

var host = builder.Build();

// 主动检查并更新Service Worker
var serviceWorkerManager = host.Services.GetRequiredService<IServiceWorkerManager>();
await serviceWorkerManager.RegisterAsync();
var updateResult = await serviceWorkerManager.CheckForUpdateAsync();

if (updateResult.IsNewVersionAvailable)
{
    Console.WriteLine("发现新版本，Service Worker已开始更新");
}

await host.RunAsync();

前端JS监听更新（index.html）

在index.html的body末尾添加：

<script>
navigator.serviceWorker.register('service-worker.js')
  .then(registration => {
    // 页面加载时主动检查更新
    registration.update();
    
    // 监听Service Worker更新完成事件
    registration.addEventListener('updatefound', () => {
      const newWorker = registration.installing;
      newWorker.addEventListener('statechange', () => {
        if (newWorker.state === 'installed' && navigator.serviceWorker.controller) {
          if (confirm('应用已更新，请点击确定刷新页面')) {
            window.location.reload();
          }
        }
      });
    });
  });
</script>

2.3 自定义Service Worker缓存校验逻辑 #

修改默认的service-worker.js，确保请求DLL时校验blazor.boot.json中的最新哈希，强制替换旧缓存：

self.addEventListener('fetch', (event) => {
  const requestUrl = new URL(event.request.url);
  
  // 仅处理框架DLL请求
  if (requestUrl.pathname.startsWith('/_framework/') && requestUrl.pathname.endsWith('.dll')) {
    event.respondWith(
      caches.open('blazor-resources').then(async (cache) => {
        // 获取最新的blazor.boot.json
        const bootResponse = await fetch('/_framework/blazor.boot.json');
        const bootData = await bootResponse.json();
        
        const dllFileName = requestUrl.pathname.split('/').pop();
        // 检查当前DLL是否在最新资源列表中
        const isResourceValid = bootData.resources.some(res => res.url.includes(dllFileName));
        
        if (isResourceValid) {
          // 资源有效，优先用缓存，无缓存则拉取
          const cachedResponse = await cache.match(event.request);
          return cachedResponse || fetch(event.request).then((newResponse) => {
            cache.put(event.request, newResponse.clone());
            return newResponse;
          });
        } else {
          // 旧资源，删除缓存并拉取最新版本
          await cache.delete(event.request);
          const newResponse = await fetch(event.request);
          cache.put(event.request, newResponse.clone());
          return newResponse;
        }
      })
    );
  } else {
    // 其他请求使用默认缓存逻辑
    event.respondWith(
      caches.match(event.request).then((cachedResponse) => {
        return cachedResponse || fetch(event.request);
      })
    );
  }
});

2.4 验证修复效果 #

1. 打开浏览器开发者工具（F12），切换到Application标签页
2. 查看Cache Storage下的blazor-resources，确认旧哈希的DLL是否被移除
3. 查看Service Workers，确认是否加载了最新的Service Worker实例
4. 部署新版本后，用长期未访问的测试账号验证，是否自动加载新DLL

内容的提问来源于stack exchange，提问作者Mike