在IIS中为.NET 8静态HTML引入服务器生成变量的低开销方案

1. 静态资源哈希命名 + 服务端映射替换 #

这是最可靠的长期缓存方案，核心思路是让静态资源文件名随内容变化自动生成哈希后缀（比如bundle.js变为bundle.abc123.js），同时服务端动态替换HTML中的资源引用路径：

实现步骤 #

• 构建时生成哈希资源：在.csproj中添加MSBuild任务，发布时自动为JS/CSS生成带哈希的文件名，并导出资源映射文件（如asset-manifest.json）：

  <Target Name="HashStaticAssets" AfterTargets="Publish">
    <ItemGroup>
      <StaticAssets Include="$(PublishDir)wwwroot\js\*.js;$(PublishDir)wwwroot\css\*.css" />
    </ItemGroup>
    <Hash Files="@(StaticAssets)" OutputFile="$(PublishDir)wwwroot\asset-manifest.json" Format="Json" />
  </Target>
  

• 服务端中间件替换引用：在Program.cs中添加中间件，拦截index.html请求时，读取映射文件替换资源路径：

  app.Use(async (context, next) =>
  {
      if (context.Request.Path == "/index.html")
      {
          var manifestPath = Path.Combine(env.ContentRootPath, "wwwroot", "asset-manifest.json");
          var manifest = JsonSerializer.Deserialize<Dictionary<string, string>>(await File.ReadAllTextAsync(manifestPath));
          
          var htmlContent = await File.ReadAllTextAsync(Path.Combine(env.ContentRootPath, "wwwroot", "index.html"));
          foreach (var (original, hashed) in manifest)
          {
              htmlContent = htmlContent.Replace(original, hashed);
          }
          
          context.Response.ContentType = "text/html";
          await context.Response.WriteAsync(htmlContent);
          return;
      }
      await next();
  });
  
  // 配置静态资源长期缓存（哈希文件名变更才会触发刷新）
  app.UseStaticFiles(new StaticFileOptions
  {
      OnPrepareResponse = ctx =>
      {
          ctx.Context.Response.Headers.Append("Cache-Control", "public, max-age=31536000, immutable");
      }
  });
  

2. 轻量版本号注入中间件 #

如果不想修改文件名，可通过服务端动态注入版本参数（如?v=1.0.0）实现缓存刷新，完全无需额外依赖：

实现步骤 #

• 在index.html中给资源路径添加版本占位符：

  <script src="/js/main.js?v={VERSION}"></script>
  <link rel="stylesheet" href="/css/style.css?v={VERSION}">
  

• 在Program.cs中添加中间件，替换占位符为程序集版本或Git提交哈希：

  // 可替换为Git提交哈希、构建编号等唯一标识
  var appVersion = Assembly.GetExecutingAssembly().GetName().Version?.ToString() ?? Guid.NewGuid().ToString();
  
  app.Use(async (context, next) =>
  {
      if (context.Request.Path == "/index.html")
      {
          var htmlPath = Path.Combine(env.ContentRootPath, "wwwroot", "index.html");
          var htmlContent = await File.ReadAllTextAsync(htmlPath);
          htmlContent = htmlContent.Replace("{VERSION}", appVersion);
          
          context.Response.ContentType = "text/html";
          await context.Response.WriteAsync(htmlContent);
          return;
      }
      await next();
  });
  
  // 带版本参数的资源设置长期缓存，无版本的资源（如index.html）设置短期缓存
  app.UseStaticFiles(new StaticFileOptions
  {
      OnPrepareResponse = ctx =>
      {
          var cacheHeader = ctx.Context.Request.Query.ContainsKey("v") 
              ? "public, max-age=31536000, immutable" 
              : "public, max-age=600";
          ctx.Context.Response.Headers.Append("Cache-Control", cacheHeader);
      }
  });
  

关于Razor的引入问题 #

你并没有过度纠结——仅为替换版本号引入Razor视图引擎确实冗余。Razor提供了完整的视图渲染能力，但你只需要简单的字符串替换逻辑，完全没必要为这点需求增加架构复杂度和依赖。

要不要继续用搜索替换方式？ #

不建议继续使用。搜索替换容易出现匹配错误、替换遗漏、多环境版本不一致等问题，随着静态资源或HTML结构变化，维护成本会快速上升。上述中间件或哈希命名方案更可靠且开销极低，是更优选择。

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