ASP.NET Core MAUI项目中解决静态资源过滤任务失败的技巧

问题背景

在将MAUI项目从.NET 8升级到.NET 9时，开发者可能会遇到一个棘手的构建错误："FilterStaticWebAssetEndpoints"任务意外失败。这个错误通常表现为构建过程中突然中断，并显示"An item with the same key has already been added"的异常信息。

错误现象分析

当使用Visual Studio构建MAUI项目时，系统会在处理静态Web资源时抛出以下关键错误：

1. 错误代码MSB4018，指示任务执行失败
2. 异常类型为ArgumentException，提示有重复键被添加
3. 错误发生在静态Web资产和Scoped CSS相关的构建任务中

值得注意的是，同样的项目通过命令行工具dotnet build却能正常构建，这表明问题可能与Visual Studio的构建流程有关。

根本原因

经过深入分析，发现这类问题通常源于项目配置中的几个常见陷阱：

1. 重复的MAUI项目引用：解决方案中存在多个被标记为MAUI的项目相互引用
2. 静态资源冲突：不同项目间存在相同路径或名称的静态资源文件
3. 不兼容的SDK版本：预览版SDK与稳定版工具链之间的兼容性问题

解决方案

1. 检查项目引用结构

确保解决方案中只有一个主项目使用<UseMaui>true</UseMaui>设置。如果共享库项目不需要完整的MAUI功能，应该：

• 移除共享项目中的UseMaui标签
• 仅保留实际需要的核心NuGet包
• 避免在库项目中引用完整的MAUI SDK

2. 清理构建环境

执行以下清理步骤：

1. 删除所有项目的bin和obj目录
2. 执行干净的重新构建
3. 考虑重置NuGet包缓存

3. 配置静态资源处理

在项目文件中添加以下配置可以解决部分资源冲突：

<Target Name="RemoveConflictingAssets" BeforeTargets="ResolveStaticWebAssetsConfiguration">
    <ItemGroup>
        <StaticWebAsset Remove="@(StaticWebAsset)" Condition="'%(Extension)' == '.gz'" />
    </ItemGroup>
</Target>

4. 调整CSS处理设置

对于不需要Scoped CSS功能的项目，可以禁用相关处理：

<DisableScopedCssBundling>true</DisableScopedCssBundling>

最佳实践建议

1. 项目结构设计：保持清晰的层次结构，避免循环引用
2. 资源管理：为静态资源使用明确的命名空间或前缀
3. 版本控制：谨慎使用预览版SDK，特别是生产环境
4. 构建工具：定期验证命令行和IDE构建结果的一致性

总结

这类构建错误虽然表象复杂，但通常源于项目配置的基本问题。通过系统性地检查项目引用、清理构建环境和合理配置资源处理，大多数情况下都能有效解决问题。对于MAUI这类跨平台框架，保持项目结构的清晰和简洁尤为重要。