FluentUI Blazor 在 .NET 9 混合项目中的 CSS 加载问题解析

问题背景

在 .NET 9 环境中使用 Visual Studio 模板创建混合 Blazor 项目（包含 MAUI Blazor、RCL 和 Blazor Web）时，开发者可能会遇到 FluentUI Blazor 组件库的 CSS 样式突然失效的问题。这个问题的典型表现是：项目初始运行时样式正常，但几天后 CSS 加载异常，导致组件失去 FluentUI 的视觉样式。

问题现象

开发者观察到以下具体现象：

1. 项目初始运行时，浏览器检查工具中可以看到正确的 CSS 导入语句
2. 一段时间后，Blazor Web 应用中的 {PROJECT_NAME}.styles.css 文件内容被替换为 App.razor 的内容
3. MAUI Blazor 部分不受影响，CSS 加载正常
4. 尝试清除浏览器缓存、重建项目、删除 bin/obj 目录等方法均无效

根本原因分析

经过技术专家深入调查，发现该问题主要由以下几个因素共同导致：

1. 静态文件中间件配置不当：在 .NET 9 中需要使用新的 app.MapStaticAssets() 方法替代传统的 app.UseStaticFiles()

2. 资源引用方式问题：CSS 文件引用未使用 Blazor 推荐的 @Assets 指令语法

3. 样式冲突：项目中残留的 Bootstrap CSS 与 FluentUI 样式产生潜在冲突

4. CSS 隔离机制：Blazor 的 CSS 隔离功能在混合项目中表现不一致

解决方案

1. 更新静态文件配置

在 Program.cs 文件中，将原有的静态文件配置替换为：

app.MapStaticAssets();

2. 修正资源引用方式

修改 App.razor 文件中的资源引用，使用 @Assets 指令：

<link rel="stylesheet" href="@Assets["_content/pTodo.Shared/app.css"]" />

3. 清理冲突样式

建议完全移除项目中的 Bootstrap CSS 引用，避免与 FluentUI 产生样式冲突。

4. 优化基础样式

在共享的 app.css 文件中，添加 FluentUI 的基础重置样式：

@import '/_content/Microsoft.FluentUI.AspNetCore.Components/css/reboot.css';

并采用 FluentUI 的设计系统样式替代原有的 Bootstrap 样式。

最佳实践建议

1. 统一样式体系：在混合项目中，建议完全采用 FluentUI 的设计系统，避免混用多个 UI 框架

2. 资源引用规范：始终使用 Blazor 推荐的资源引用方式，确保在不同渲染模式下的一致性

3. 版本适配：注意 .NET 版本更新带来的 API 变化，及时调整项目配置

4. 样式隔离：合理使用 CSS 隔离功能，避免全局样式污染

未来改进

FluentUI Blazor 团队已计划在 4.11.0 版本中提供专门针对 Blazor Hybrid + Web 应用的模板，这将从根本上解决此类配置问题。开发者可以关注后续版本更新，获取开箱即用的最佳实践配置。

总结

混合 Blazor 项目中的 CSS 加载问题往往涉及多个层面的因素，需要开发者理解 Blazor 的资源加载机制、样式隔离原理以及不同渲染模式下的差异。通过本文提供的解决方案，开发者可以系统性地解决 FluentUI 在 .NET 9 混合项目中的样式加载问题，同时建立起更健壮的前端架构实践。