Avalonia 快速上手指南：用 C# 和 XAML 构建跨平台 UI 应用
【免费下载链接】AvaloniaDevelop Desktop, Embedded, Mobile and WebAssembly apps with C# and XAML. The future of .NET UI项目地址: https://gitcode.com/GitHub_Trending/ava/Avalonia
同一套界面代码在 Windows、macOS、Linux 上都要能跑，是桌面应用开发里最现实的诉求之一。Avalonia 是一个 .NET 跨平台 UI 框架，让你用 C# 和 XAML 编写一次界面代码，就能在 Windows、macOS、Linux、iOS、Android 和 WebAssembly 上运行。本指南基于仓库当前源码，带你走完从安装到本地构建的基本路径。
一句话定位
Avalonia 常被视作 WPF 的精神续作：界面用 XAML 描述，逻辑用 C# 的 MVVM 模式组织，样式系统类似 WPF 但并非 1:1 复制。官方 README 说明它已成熟到可用于生产环境，Schneider Electric、Unity、JetBrains 等团队在用它。它适合从 WPF 迁移、或想统一多平台 UI 的 .NET 开发者。
特性速览
| 特性 | 它做了什么 | 谁需要关注 |
|---|---|---|
| 多平台目标 | 一套代码覆盖 Windows、macOS、Linux，并支持 iOS、Android 与 WebAssembly（见 build/TargetFrameworks.props） | 所有使用者 |
| XAML + MVVM | 界面声明式描述，样式可主题化，内置 Fluent、Simple 两套主题（src/Avalonia.Themes.Fluent/） | 界面开发者 |
| NuGet 分发 | 主包加平台包即可接入，无需从源码编译 | 所有使用者 |
| 编辑器支持 | VS Code 扩展、Visual Studio 扩展、Rider 均提供模板、XAML 预览与代码补全（见 readme.md） | 日常写码的人 |
| 示例库 ControlCatalog | 数百个控件页面的演示应用，便于逐个试验控件行为 | 新手查用法 |
| API 兼容策略 | 主版本内保持源码与二进制兼容，CI 自动做 API 校验，破坏性变更需团队审批 | 关注升级风险的团队 |
上手走一遍
1. 安装 NuGet 包
最简单的方式是通过 NuGet 安装主包和桌面平台包，这是官方 README 给出的接入方式：
Install-Package Avalonia Install-Package Avalonia.Desktop应用入口需要实现BuildAvaloniaApp()方法，它负责组装框架并选择平台后端：
public static AppBuilder BuildAvaloniaApp() => AppBuilder.Configure<App>() .UsePlatformDetect() .LogToTrace();.UsePlatformDetect()会根据当前操作系统自动选择后端，跨平台项目通常只写这一份。想看控件效果，仓库里的 samples/ControlCatalog/ 是最直观的入口；想理解 MVVM 最小实现，可以看 samples/MiniMvvm/，它只有四个源文件。
2. 在 macOS 上配置原生库路径
macOS 平台的后端包含 Objective-C 原生组件，位于 native/Avalonia.Native/src/OSX/。如果你用 Xcode 单独编译了原生库，可以把产物路径注入应用，避免每次全量重编。AvaloniaNativePlatformOptions的用法在 docs/macos-native.md 中有完整说明：
.With(new AvaloniaNativePlatformOptions { AvaloniaNativeLibraryPath = "/path/to/Avalonia.Native.dylib" })3. 从源码克隆构建
如果你需要自己构建，仓库地址为：
git clone https://gitcode.com/GitHub_Trending/ava/Avalonia构建指令（Nuke 任务、原生库编译等细节）以仓库内的 docs/index.md 和官方文档为准；仓库要求 .NET 10 SDK（见 global.json）。
坑与注意事项
- 不是 WPF 的完全替代：README 明确说它相似但不是 1:1 复制，迁移 WPF 代码时个别行为需要调整，可参考 docs/porting-code-from-3rd-party-sources.md。
- 主版本升级有破坏性变更：README 指向了 Avalonia 11 到 12 的 breaking changes 文档。仓库当前的开发版号是 12.2.999（见 build/SharedVersion.props），生产环境请认准 NuGet 上的稳定版。
- API 兼容只保证主版本内：官方策略是主版本内保持源码和二进制兼容，破坏性变更须审批（docs/api-compat.md），跨大版本升级前建议先看变更记录。
- iOS、Android、WASM 属于扩展支持：README 描述中对 Android、iOS 和 WebAssembly 标注为 experimental 级别的表述见 build/SharedVersion.props 中的包描述，用于正式项目前建议先在示例上验证。
- macOS 原生组件需要单独处理：改原生代码要么走
AvaloniaNativeLibraryPath注入，要么全量重编，两条路径的取舍见 docs/macos-native.md。
收尾
日常使用以 NuGet 稳定包加 samples/ 中的示例为起点即可，深入开发再看 docs/index.md。贡献代码前先读 CONTRIBUTING.md，项目采用 MIT 许可（licence.md）。
【免费下载链接】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），仅供参考
