写给每一位想用 C# 写出跨平台桌面应用的开发者

🤔 你是否也有这样的困惑？

刚接触 Avalonia 的时候，不少开发者卡在了"第一步"——环境搭建。

明明照着网上的教程一步步操作，结果 dotnet new 跑出来没有 Avalonia 模板；或者 SDK 版本对不上，编译直接报错；再或者 NuGet 源没配好，包死活下不下来。一顿折腾两三个小时，Hello World 都没跑起来，挫败感拉满。

这篇文章就是为了解决这个问题。

读完之后，你将掌握：从零到一完整搭建 Avalonia 开发环境的标准流程，包括 .NET SDK 的版本选择与验证、Avalonia 模板的安装与更新、常见报错的排查思路，以及创建并运行第一个项目的完整步骤。整个过程控制在 30 分钟以内，可直接落地到实际项目中。

🧩 先搞清楚：Avalonia 到底是什么？

在动手之前，咱们先花两分钟把概念摸清楚，后面操作起来才不会懵。

Avalonia 是一个基于 .NET 的开源跨平台 UI 框架，设计理念上和 WPF 非常接近——同样用 XAML 描述界面，同样支持数据绑定和 MVVM 模式。但它最大的不同在于：一套代码，能跑在 Windows、macOS、Linux，甚至 iOS、Android 和 WebAssembly 上。

对于长期做 Windows 桌面开发的 C# 开发者来说，Avalonia 的学习曲线相当平缓。如果你熟悉 WPF，上手 Avalonia 基本不需要太多额外学习成本。而对于想从 Windows 走向全平台的团队，Avalonia 是目前 .NET 生态里最成熟的选择之一。

🛠️ 第一步：安装 .NET SDK

版本要求

Avalonia 目前要求 .NET 8.0 或更高版本。这一点需要特别注意——很多老项目可能还跑在 .NET 6 甚至 .NET Framework 上，但 Avalonia 的模板和工具链已经全面迁移到 .NET 8+。

当然，.NET 支持多版本共存，你完全可以在同一台机器上同时装着 .NET 6、.NET 8、.NET 9，它们互不干扰。

下载与安装

前往 dotnet.microsoft.com 下载对应操作系统的 SDK 安装包。

Windows：下载 .exe 安装程序，一路 Next 即可
macOS：下载 .pkg 安装包，或者通过 Homebrew 安装：

bash
brew install --cask dotnet-sdk

Linux（Ubuntu/Debian 系）：

bash
sudo apt-get update
sudo apt-get install -y dotnet-sdk-8.0

验证安装是否成功

安装完成后，打开终端（Windows 用 PowerShell 或 CMD），执行：

bash
dotnet --version

如果输出类似 8.0.xxx 或 10.0.xxx 的版本号，说明安装成功。

想查看当前机器上装了哪些版本的 SDK，执行：

bash
dotnet --list-sdks

输出示例：

📦 第二步：安装 Avalonia 项目模板

.NET SDK 本身并不自带 Avalonia 的项目模板，需要单独安装。这一步是很多新手卡壳的地方。

安装命令

bash
dotnet new install Avalonia.Templates

Avalonia 要求 .NET 8+，正常情况下直接用 install 子命令就行。

安装成功后，终端会输出一张模板清单，大概长这样：


Template Name                                Short Name                   Language    Tags
-------------------------------------------- ---------------------------- ----------- ---------------------------------------------------------
Avalonia .NET App                            avalonia.app                 [C#],F#     Desktop/Xaml/Avalonia/Windows/Linux/macOS
Avalonia .NET MVVM App                       avalonia.mvvm                [C#],F#     Desktop/Xaml/Avalonia/Windows/Linux/macOS
Avalonia Cross Platform Application          avalonia.xplat               [C#],F#     Desktop/Xaml/Avalonia/Browser/Mobile
Avalonia Resource Dictionary                 avalonia.resource                        Desktop/Xaml/Avalonia/Windows/Linux/macOS
Avalonia Styles                              avalonia.styles                          Desktop/Xaml/Avalonia/Windows/Linux/macOS
Avalonia TemplatedControl                    avalonia.templatedcontrol    [C#],F#     Desktop/Xaml/Avalonia/Windows/Linux/macOS
Avalonia UserControl                         avalonia.usercontrol         [C#],F#     Desktop/Xaml/Avalonia/Windows/Linux/macOS
Avalonia Window                              avalonia.window              [C#],F#     Desktop/Xaml/Avalonia/Windows/Linux/macOS

这几个模板各有用途，下面简单说明：

模板短名	适用场景
`avalonia.app`	最基础的 Avalonia 应用，适合快速验证和学习
`avalonia.mvvm`	带 MVVM 架构的应用，推荐入门首选
`avalonia.xplat`	跨平台（含移动端和浏览器），适合全平台项目
`avalonia.usercontrol`	单独创建一个用户控件
`avalonia.window`	单独创建一个窗口

确认模板已安装

执行以下命令，在输出列表里搜索 "Avalonia" 相关条目：

bash
dotnet new list

如果能看到上面那张表里的模板，说明安装成功。

🔄 第三步：模板的更新与版本管理

更新到最新版本

Avalonia 版本迭代较快，建议定期更新模板：

bash
dotnet new update

这条命令会更新所有已安装的模板包，包括 Avalonia.Templates。

安装指定版本

如果项目有版本锁定要求（比如团队统一用 Avalonia 11.2.0），可以指定版本安装：

bash
dotnet new install Avalonia.Templates::11.2.0

这在团队协作中非常有用——避免因为模板版本不一致导致项目结构差异。

卸载模板

如果需要干净重装，先卸载再重新安装：

bash
dotnet new uninstall Avalonia.Templates
dotnet new install Avalonia.Templates

🚀 第四步：创建并运行第一个项目

创建 MVVM 项目

对于入门学习，推荐从 MVVM 模板开始，它自带了合理的项目结构和依赖注入配置：

bash
dotnet new avalonia.mvvm -o MyFirstAvaloniaApp
cd MyFirstAvaloniaApp

项目创建完成后，目录结构大致如下：


MyFirstAvaloniaApp/
├── App.axaml              # 应用入口 XAML
├── App.axaml.cs           # 应用入口代码
├── ViewModels/
│   ├── MainWindowViewModel.cs
│   └── ViewModelBase.cs
├── Views/
│   └── MainWindow.axaml   # 主窗口 XAML
├── Models/                # 数据模型（默认空）
├── Assets/                # 静态资源
└── Program.cs             # 程序入口

这个结构已经帮你做好了 View 和 ViewModel 的分离，后续扩展非常方便。

构建与运行

bash
dotnet build
dotnet run

如果一切正常，会弹出一个窗口，显示 "Welcome to Avalonia!"。看到这句话，说明你的整个开发环境已经配置完毕。

也可以用一条命令快速验证安装是否成功（创建测试项目、构建、然后删掉）：

bash
dotnet new avalonia.app -o TestApp
cd TestApp
dotnet build
cd ..
rm -rf TestApp   # Windows 用 rmdir /s /q TestApp

🔧 常见问题排查

问题一：`dotnet new` 找不到 Avalonia 模板

现象：执行 dotnet new avalonia.mvvm 报错"No templates found matching..."

排查步骤：

先确认模板是否安装：dotnet new list | grep -i avalonia
没有的话重新安装：dotnet new install Avalonia.Templates
还不行？检查 NuGet 源配置（见下方）

问题二：`Avalonia.Templates` 包找不到

这通常是 NuGet 源没配置好。执行：

bash
dotnet nuget list source

确认输出里有 nuget.org 并且状态是 [Enabled]：


Registered Sources:
  1.  nuget.org [Enabled]
      https://api.nuget.org/v3/index.json

如果没有，手动添加：

bash
dotnet nuget add source https://api.nuget.org/v3/index.json -n nuget.org

国内网络如果访问 nuget.org 较慢，可以配置镜像源（如 Azure 中国区镜像或公司内网 NuGet 服务器），但要确保镜像源里有 Avalonia 相关包。

问题三：Linux 下需要 `sudo` 权限

在某些 Linux 发行版上，全局安装 .NET 工具可能需要 root 权限。如果遇到权限问题，在命令前加 sudo：

bash
sudo dotnet new install Avalonia.Templates

问题四：`global.json` 锁定了 SDK 版本

如果项目根目录有 global.json 文件，它会强制指定 SDK 版本。检查文件内容：

json
{
  "sdk": {
    "version": "6.0.100"
  }
}

如果版本低于 8.0，要么修改这个文件，要么安装对应版本的 SDK。

🖥️ IDE 选择与插件配置

命令行搞定了环境，IDE 这边也要配置好，不然写 XAML 就是"盲写"——没有预览、没有智能提示，效率极低。

Windows 开发者推荐 Visual Studio 2022，在 Marketplace 搜索并安装 "Avalonia for Visual Studio" 扩展。安装后，VS 会自动包含 Avalonia 模板，并提供 XAML 预览器。

macOS / Linux 开发者推荐 JetBrains Rider，配合 AvaloniaRider 插件，可以实时预览 XAML 变更，开发体验非常流畅。Rider 在非 Windows 平台上对 Avalonia 的支持是最完整的。

VS Code 也有 Avalonia 扩展，但功能相对有限，适合轻量场景或者习惯 VS Code 的开发者。官方文档明确提示：不推荐作为主力 IDE 使用。

💡 三句话总结核心要点

Avalonia 需要 .NET 8.0+，版本不对是第一大坑。

模板安装靠 dotnet new install Avalonia.Templates，一行命令搞定，NuGet 源要先确认正常。

入门首选 avalonia.mvvm 模板，结构清晰，直接对接 MVVM 最佳实践。

🎯 结尾：下一步去哪儿？

到这里，你的 Avalonia 开发环境已经完整搭建起来了。一个能跑的 MVVM 项目结构也已经在手边了。

接下来的学习路径可以这样走：先把 XAML 基础语法和数据绑定搞熟，这是 Avalonia 开发的核心地基；然后深入 ReactiveUI（Avalonia 官方推荐的 MVVM 框架），理解响应式编程思路；再之后可以研究样式系统与主题定制，让界面真正好看起来；最后再挑战跨平台发布与打包，把应用部署到 Windows、macOS、Linux 三端。

每一步都有很多值得细说的内容，后续文章会逐步展开。

欢迎在评论区聊聊你在搭建 Avalonia 环境时遇到的坑——是 SDK 版本问题、NuGet 网络问题，还是 IDE 配置问题？你的经历可能正好帮到同样在踩坑的人。

#C# #Avalonia #跨平台开发 #.NET #桌面应用开发

Avalonia 官方文档 Avalonia 中文文档

目录