Avalonia 入门指南：一套 .NET 代码如何同时跑通 Windows、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
如果你的桌面应用只跑在 Windows 上，而用户催你上 Mac 和 Linux，重写一遍 UI 基本是天方夜谭。Avalonia 就是为此而生的开源跨平台 UI 框架：用 C# 和 XAML 写一次界面，通过 Skia 渲染引擎分发到桌面、移动端甚至 WebAssembly，官方称它是 .NET UI 的未来。
💡 价值速览：这套框架能帮你省掉什么
- 一份代码，多端部署：Windows、macOS、Linux、iOS、Android、WebAssembly 全部支持，不用为每个平台单写 UI
- WPF 背景零门槛：XAML 语法、MVVM 模式、数据绑定概念一脉相承，熟悉 WPF 的你几乎不需要重新学
- 完全免费开源：MIT 协议，企业和个人商用都没有授权费压力
- 控件开箱即用：从按钮、菜单到日期选择、颜色拾取器，官方示例直接给你看效果
- 大厂在用的成熟度：Unity、JetBrains、GitHub 等团队已在生产环境使用，不是玩具项目
🧰 上手准备：Avalonia 环境搭建完整清单
开始之前，把这几样工具备齐，后面所有步骤都依赖它们：
- .NET SDK：仓库要求 .NET 10（见 global.json），装最新 SDK 即可自动满足
- 编辑器：Visual Studio 2022、VS Code 或 Rider 三选一，都支持 Avalonia，装上对应扩展可获得 XAML 预览和补全
- 代码仓库：clone 下来看源码和示例
git clone https://gitcode.com/GitHub_Trending/ava/Avalonia- NuGet 包管理器：Avalonia 通过 NuGet 分发，核心包就两个——
Avalonia和Avalonia.Desktop - 目标平台工具（可选）：做 macOS 装 Xcode，做移动端装对应 SDK
小贴士：只是试用控件库的话，连仓库都不用 clone，直接装 NuGet 包就能开工。
🔍 关键差异：Avalonia 和 WPF 到底改了什么
这是 WPF 开发者最关心的问题。好消息是：改动比你想象的小得多。
命名空间与项目结构的映射
- WPF 的
System.Windows.*在 Avalonia 里变成Avalonia.Controls、Avalonia.Media等 - 大部分控件名、布局面板、样式写法保持不变
- 项目结构上推荐"单主项目 + 平台子项目"的组织方式，仓库里 ControlCatalog 就演示了同一套界面如何派生出 Desktop、Android、iOS、Browser 多个入口
渲染引擎：从系统依赖到 Skia 统一渲染
WPF 依赖 Windows 图形栈，所以跨不了平台；Avalonia 用 Skia 自绘整套界面，换来的是各平台像素级一致的视觉表现。下面的测试图就是它的矢量图形渲染输出效果：
注意这不是"尽量像"，而是"就是"——曲线、文字、图片在所有平台上走同一条渲染管线。
🛤️ 实战路线：三步走，从跑通到成型
别一上来就规划整个应用，按这个顺序走最省力：
第一步：跑通最小窗口
打开 samples/Sandbox，这是一个几行文件构成的最小 Avalonia 应用：一个入口类、一个窗口、一点 XAML。先把它编译运行起来，建立"这套框架确实能跑"的信心。如果你只想看最极简的启动结构，samples/AppWithoutLifetime 更短。
第二步：把控件库逛一遍
打开 samples/ControlCatalog，官方控件展示目录：按页面分类展示每个控件的外观、参数和可交互状态。你的目标是带着自己项目的界面需求逛一遍——哪页有你要的效果，就记下那一页的写法。高级绘制需求可以顺路看 samples/RenderDemo。
第三步：搭骨架，补平台差异
- 搭骨架：参考 samples/MiniMvvm 里的轻量 MVVM 写法（几个百行以内的文件），把 ViewModel 和视图分开
- 补平台差异：桌面特性、macOS 菜单栏、Linux 的 DBus 集成等，Avalonia 都提供了现成抽象，不用自己碰底层。macOS 原生渲染的细节可以看 docs/macos-native.md
走到这里，你手里就是一个"桌面三平台 + 按需扩展移动端"的可交付应用了。
❓ 新手 FAQ：最容易卡住的三个问题
问：我现有的 WPF 项目能直接搬过来吗？
答：XAML 和大部分逻辑可以复用，但命名空间、平台特定 API 需要适配，不是 1:1 拷贝。建议按页面小步迁移，而不是一次性整体替换。
问：不装 Visual Studio 能做 Avalonia 开发吗？
答：可以。VS Code 或 Rider 配上 Avalonia 扩展，同样有补全和诊断，命令行加 NuGet 包就是完整开发环境。
问：免费版有功能阉割吗？
答：没有。核心框架是 MIT 开源协议，功能完整免费。仓库里的商业授权（Avalonia XPF）是面向"几乎零改动跑老 WPF 应用"的另一条产品线，与开源主框架无关。
📚 延伸资源：按目录深挖
- 文档：docs/ 目录下的开发说明，重点看 NuGet 打包指南、API 兼容策略 和 第三方代码移植指南
- 示例项目：samples/ 是全仓库最值钱的目录，ControlCatalog 看控件、RenderDemo 看渲染、IntegrationTestApp 看跨平台集成
- 测试用例：tests/ 里的渲染测试文件本身就是最好的"官方视觉标准"，想知道某个效果在 Avalonia 里长什么样，直接翻对应的期望图
- 主题样式：src/Avalonia.Themes.Fluent 是默认现代主题源码，想自定义暗色模式就从这个方向入手
🎯 现在就动手
先 clone 仓库，跑起来 Sandbox，再逛一圈 ControlCatalog——两小时内你就能确认这套跨平台 UI 框架适不适合你的项目。剩下的，就是把你自己的界面一页页搬进去了。
【免费下载链接】AvaloniaDevelop Desktop, Embedded, Mobile and WebAssembly apps with C# and XAML. The future of .NET UI项目地址: https://gitcode.com/GitHub_Trending/ava/Avalonia
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
