Avalonia怎么在WebAssembly上运行？Avalonia for WASM详细教程

Avalonia是一个基于.NET的跨平台UI框架，原本常用于桌面程序开发。通过官方提供的WebAssembly支持，我们可以将Avalonia应用编译为WASM并在浏览器中运行，实现一套C#代码同时覆盖桌面与Web端。

环境准备

在开始之前，请确保已安装以下工具：

• .NET 8 SDK或更高版本
• 支持WASM发布的Avalonia模板
• 任意现代浏览器用于测试

创建Avalonia WASM项目

使用命令行创建一个空白的Avalonia跨平台项目，并添加浏览器支持。最简单的方式是通过官方模板：

dotnet new install Avalonia.Templates
dotnet new avalonia.app -o MyAvaloniaWasm
cd MyAvaloniaWasm
dotnet add package Avalonia.Browser

配置程序入口

打开项目中的Program.cs文件，将其改为浏览器启动方式。核心是使用Avalonia.Browser中的扩展方法。

using System.Runtime.Versioning;
using Avalonia;
using Avalonia.Browser;
using Avalonia.ReactiveUI;
using MyAvaloniaWasm;

[assembly: SupportedOSPlatform("browser")]

internal sealed partial class Program
{
    private static void Main(string[] args)
    {
        // 在浏览器中启动Avalonia应用
        BuildAvaloniaApp()
            .UseReactiveUI()
            .SetupBrowserApp("out");
    }

    public static AppBuilder BuildAvaloniaApp()
        => AppBuilder.Configure<App>()
            .UsePlatformDetect()
            .LogToTrace();
}

修改项目文件

需要在csproj中指定浏览器作为目标框架，并关闭一些桌面专属功能。参考配置如下：

<Project Sdk="Microsoft.NET.Sdk">
  <PropertyGroup>
    <TargetFramework>net8.0-browser</TargetFramework>
    <Nullable>enable</Nullable>
    <BuiltInComInteropSupport>false</BuiltInComInteropSupport>
  </PropertyGroup>
  <ItemGroup>
    <PackageReference Include="Avalonia.Browser" Version="11.0.0" />
  </ItemGroup>
</Project>

构建与发布

执行以下命令可将应用发布为静态Web资源：

dotnet publish -c Release -o dist

发布完成后，dist文件夹中会包含index.html与对应的WASM文件。你可以使用任意静态服务器查看效果：

cd dist
python3 -m http.server 8080

常见问题

为什么页面空白

多数情况是因为未正确调用SetupBrowserApp，或csproj中TargetFramework未设置为net8.0-browser。请检查Program.cs是否使用了Avalonia.Browser命名空间。

能访问本地文件吗

WASM运行在沙箱中，不能直接读写用户磁盘。如需持久化，应使用浏览器提供的IndexedDB或通过网络接口与后端通信。

小结

通过上述步骤，我们完成了Avalonia在WebAssembly上的基础运行配置。这种方式适合需要将现有Avalonia界面快速迁移到Web的场景，后续可结合Blazor或JS互操作扩展能力。

AvaloniaWebAssemblyWASM修改时间：2026-07-27 01:39:20