Blazor WASM偶现平台启动失败问题求助：部署后常触发Failed to start platform错误

我之前维护Blazor WASM应用时也碰到过一模一样的问题——部署新版本后频繁出现加载失败，刷新页面就恢复正常，后来排查下来确实是缓存不兼容导致的新旧资源冲突。下面是几个亲测有效的排查和解决方向：

• 先定位具体的缓存冲突点
  下次出现加载失败时，打开浏览器控制台的Network面板，查看加载失败的资源请求：

  • 如果是blazor.boot.json或者_framework下的*.dll.js文件返回404，那基本就是旧缓存的引导文件在请求已被替换的旧版本资源。
  • 如果是资源加载时出现完整性校验失败（integrity mismatch），那就是浏览器缓存的旧资源和新版本的资源哈希不匹配，被Blazor的安全机制拦截了。

• 启用Blazor内置的更新检测机制
  Blazor WASM自带了处理版本更新的能力，你可以在Program.cs里添加主动检查更新的逻辑，一旦发现资源不匹配就自动刷新页面：

  var builder = WebAssemblyHostBuilder.CreateDefault(args);
  builder.RootComponents.Add<App>("#app");
  
  var httpClient = new HttpClient { BaseAddress = new Uri(builder.HostEnvironment.BaseAddress) };
  builder.Services.AddScoped(sp => httpClient);
  
  var host = builder.Build();
  
  // 自定义资源加载逻辑，检测到404则刷新页面
  var jsRuntime = host.Services.GetRequiredService<IJSInProcessRuntime>();
  await jsRuntime.InvokeVoidAsync("Blazor.start", new
  {
      loadBootResource = async (string type, string name, string defaultUri, string integrity) =>
      {
          var response = await httpClient.GetAsync(defaultUri, HttpCompletionOption.ResponseHeadersRead);
          if (response.StatusCode == HttpStatusCode.NotFound)
          {
              // 旧资源不存在，触发页面刷新获取最新版本
              jsRuntime.InvokeVoidAsync("location.reload");
              return null;
          }
          return await response.ReadAsStreamAsync();
      }
  });
  
  await host.RunAsync();
  

• 配置服务器端的精准缓存策略
  这是最根本的解决办法，不同服务器的配置方式略有不同，核心原则是：

  • 对于index.html、blazor.boot.json这类引导文件，设置短缓存（比如5分钟）或者禁止缓存，确保浏览器每次都从服务器拉取最新版本。
  • 对于带内容哈希的静态资源（比如*.dll.js、*.css、*.png），设置长期缓存（比如1年），因为文件名里的哈希值会随内容变化，不会出现新旧资源混淆的问题。

  举个Nginx的配置示例：

  # 引导文件和入口页面设置短缓存
  location / {
      try_files $uri $uri/ /index.html;
      expires 5m;
      add_header Cache-Control "no-cache, must-revalidate";
  }
  
  # 哈希资源设置长期缓存
  location ~* \.(dll.js|css|jpg|png|woff2)$ {
      expires 1y;
      add_header Cache-Control "public, immutable";
  }
  

• 手动添加版本标识（备选方案）
  如果你不想依赖自动生成的哈希文件名，可以手动在index.html的资源引用后添加版本参数，每次部署新版本时更新这个版本号：

  <link href="css/app.css?v=20240520" rel="stylesheet" />
  <script src="_framework/blazor.webassembly.js?v=20240520"></script>
  

  这样浏览器会把带新版本参数的资源当成全新资源，不会使用旧缓存。

• CDN缓存刷新（如果使用了CDN）
  如果你用了CDN加速静态资源，部署新版本后一定要记得刷新CDN的对应资源缓存，不然CDN会继续返回旧版本的资源，导致浏览器加载失败。多数CDN支持按目录刷新，直接刷新/_framework/目录下的所有资源即可。

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