Avalonia 实战指南：把 WPF 应用搬上 macOS 和 Linux

Avalonia 实战指南：把 WPF 应用搬上 macOS 和 Linux

【免费下载链接】AvaloniaDevelop Desktop, Embedded, Mobile and WebAssembly apps with C# and XAML. The future of .NET UI项目地址: https://gitcode.com/GitHub_Trending/ava/Avalonia

WPF 项目跑得好好的，产品说"客户要 macOS 和 Linux 版本"，你卡住了。这不是你的代码写得不够好，是 WPF 依赖 Win32 和 DirectX，天生只认 Windows。Avalonia 就是为这个场景存在的：.NET 的跨平台 UI 框架，复用你已有的 XAML 与 MVVM 技能，一套代码覆盖 Windows、macOS、Linux、Android、iOS、tvOS 和 WebAssembly，默认由 Skia 渲染引擎出图，保证各平台视觉一致。

用最小成本完成 WPF 到 Avalonia 的迁移

迁移的真实工作量没想象中吓人：大多数 WPF XAML 可以近乎原样搬走，因为两者的数据绑定、样式、模板概念几乎一一对应。主要动作是命名空间替换，System.Windows系整体映射到Avalonia系：

WPF 里有的控件 Avalonia 基本都有，个别缺失的用现成包补：DataGrid 用 CommunityToolkit.DataGrid.Avalonia，ColorPicker 有官方包 Avalonia.Controls.ColorPicker。MVVM 层几乎零改动——Avalonia 只要求你通知PropertyChanged，你用的任何 MVVM 库都直接生效，仓库里的 MiniMvvm 示例 就是一个只有百来行、自包含的轻量基座。

确认 Avalonia 支持的平台与渲染引擎

先搞清楚 Avalonia 支持哪些平台。核心包加Avalonia.Desktop覆盖三大桌面平台，再加 Android、iOS 平台包进移动，WebAssembly 也在一套代码内。选型时别漏了渲染引擎：默认是 Skia，矢量、位图、字体在所有平台表现一致，这也是仓库 tests/TestFiles 里大量期望截图的来源——渲染测试就是逐像素对比 Skia 输出。

需要 GPU 加速的场景可换 OpenGL、Vulkan、Metal 后端，对应源码分别在 Avalonia.OpenGL、Avalonia.Vulkan、Avalonia.Metal，按目标平台按需引入即可。

处理平台特定的差异代码

平台差异被收敛在包层面，业务代码里的分支尽量少。入口用UsePlatformDetect()自动选中当前平台的后端：

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

macOS 的窗口装饰和原生菜单走 Objective-C 原生层，源码在 native/Avalonia.Native；Linux 则通过 DBus 对接系统托盘、原生菜单和输入法，代码在 Avalonia.FreeDesktop。你平时只需要知道：这类能力在桌面三大平台开箱即用，不用自己写 IPC。

只有当你改动了 macOS 原生部分，才需要本地用 Xcode 重编出 dylib，再让 AppBuilder 指向你的构建产物：

.With(new AvaloniaNativePlatformOptions { AvaloniaNativeLibraryPath = "[Path to your dylib]" })

让 XAML 语法跨平台复用

XAML 是纯文本，平台差异全被包隔离了，所以页面文件基本不用为平台写分支。两点值得记住。

其一，资源引用用avares://方案，打包后在任何平台都能解析。ControlCatalog 的剪贴板示例直接打开avares://ControlCatalog/Assets/image1.jpg，换平台不用改一行。

其二，XAML 走编译时生成代码而非运行时反射解析，构建时由构建任务完成编译，模板项目默认已配置，写法和 WPF 时期习惯的ResourceDictionary、隐式样式、ThemeVariant暗色切换都能平移过来。

避开 WPF 迁移 Avalonia 的 4 个典型坑

• 命名空间替换要彻底：using System.Windows.*和 XAML 根的x:Class声明都别漏，否则错误散落在各处。
• WindowState在 Linux 下不可全信：部分窗口管理器不支持最大化/最小化语义，状态逻辑要留降级路径。
• 透明窗口看WindowTransparencyLevel：WPF 的透明窗口依赖 DirectX，在 Linux 上依赖 compositor，行为不一。跨平台应用建议显式声明透明度级别而不是默认值。
• 字体要自己带：Linux 环境常缺 WPF 默认的 Calibri 等字体，字形会退化。官方 Avalonia.Fonts.Inter 内置 Inter 字体，是跨平台兜底方案。

搭建本地验证环境并跑通 Hello World

动手前先把仓库里的高价值资源过一遍：ControlCatalog 是全部内置控件的目录，RenderDemo 专攻渲染表现，docs 下有 API 兼容对照表，api-compat.md逐条列了 WPF 与 Avalonia 的行为差异。要本地跑示例，先 clone 仓库：

git clone https://gitcode.com/GitHub_Trending/ava/Avalonia

最小可执行的第一步：装 Visual Studio 的 Avalonia 扩展或 VS Code 的 Avalonia for Code 插件，新建一个 Avalonia 窗口项目跑通 Hello World，然后把 WPF 里最简单的一个用户控件原样粘进去编译——能过，说明这套 XAML 可以无改动复用。接下来就是按上文的命名空间映射逐文件搬，每搬一个跑一次dotnet run，分别指向 macOS 和 Linux 目标各验一遍。

【免费下载链接】AvaloniaDevelop Desktop, Embedded, Mobile and WebAssembly apps with C# and XAML. The future of .NET UI项目地址: https://gitcode.com/GitHub_Trending/ava/Avalonia