AvaloniaUI WebAssembly 开发环境配置指南

问题背景

AvaloniaUI 是一个跨平台的 .NET UI 框架，支持通过 WebAssembly 在浏览器中运行应用程序。近期有开发者反馈，按照官方文档配置 WebAssembly 开发环境时遇到了资源加载失败的问题，特别是无法找到 avalonia.js 文件。

环境配置要点

正确的 SDK 和工具链选择

开发过程中发现，.NET SDK 版本与目标框架的匹配至关重要：

1. 当使用 .NET 9 SDK 时：

   • 若要运行 net8.0-browser 目标，必须安装 wasm-tools-net8 工作负载
   • 直接运行 dotnet workload install wasm-tools 安装的是针对 .NET 9 的工具链

2. 对于 .NET 8 SDK 用户：

   • 确保安装最新补丁版本
   • 使用标准的 wasm-tools 工作负载即可

版本兼容性问题

目前存在以下已知兼容性问题：

1. .NET 9 环境下：

   • 当目标框架设为 net9.0-browser 时，会出现资源路径错误（avalonia.js 被输出到 wwwroot 根目录而非 _framework 子目录）
   • 这是由于 .NET 运行时升级到新版 Emnscripten 导致的底层变更
   • 此问题需要等待 SkiaSharp 发布兼容版本后才能解决

2. .NET 8 环境下：

   • 确保使用 AvaloniaUI 11.1.3 或更高版本
   • 旧版 11.1.0 存在已知问题

解决方案

针对 net8.0-browser 的配置

1. 安装必要组件：

   dotnet workload install wasm-tools-net8
   dotnet new install avalonia.templates
   

2. 创建项目：

   mkdir BrowserTest
   cd BrowserTest
   dotnet new avalonia.xplat
   

3. 确保项目配置：

   • 检查 Browser 项目的 TargetFramework 是否为 net8.0-browser
   • 确认引用的 Avalonia 包版本不低于 11.1.3

针对 net9.0-browser 的临时方案

目前不建议在生产环境中使用 net9.0-browser 目标，若必须使用：

1. 可以尝试手动调整资源路径：

   • 修改 FrameworkAssetPathResolver 配置
   • 但这只是部分解决方案，仍会遇到 SkiaSharp 相关的问题

2. 更好的做法是等待官方发布完整支持 .NET 9 的版本

最佳实践建议

1. 版本一致性：

   • 保持 SDK 版本、目标框架和工作负载版本三者一致
   • 例如：.NET 8 SDK + net8.0-browser + wasm-tools

2. 模板更新：

   • 使用最新模板创建项目（11.1 版本后模板有重要更新）

3. 调试技巧：

   • 检查发布输出目录结构
   • 确认 avalonia.js 文件是否存在于 _framework 子目录
   • 查看浏览器开发者工具中的网络请求记录

总结

AvaloniaUI 的 WebAssembly 支持正在快速发展中，目前最稳定的组合是使用 .NET 8 SDK 配合 net8.0-browser 目标框架。开发者应注意版本匹配问题，特别是工作负载的选择。对于 .NET 9 的支持，建议等待官方发布完整兼容版本后再进行迁移。