1. 项目概述为什么是Avalonia如果你是从WPF、WinForms或者UWP过来的开发者第一次听说Avalonia可能会有点懵。简单来说Avalonia是一个开源的、跨平台的.NET UI框架。它的目标很明确让你能用熟悉的XAML和C#写一套代码就能在Windows、macOS、Linux、iOS、Android甚至WebAssembly上运行。听起来是不是有点像MAUI没错它们是同一赛道的选手但Avalonia出现得更早在跨平台桌面端的成熟度和社区生态上目前有它独特的优势。我最初接触Avalonia是因为一个需要同时部署在Windows工控机和Linux服务器监控屏上的项目。当时MAUI还在早期而Avalonia已经有不少生产级应用在跑了比如开源的IDE Rider部分UI、一些金融交易终端等。它的核心理念是“像素级精确”这意味着你在不同平台上能得到高度一致的渲染效果这对于需要严格控制UI表现的企业级应用来说是个巨大的加分项。环境配置是任何技术栈的“敲门砖”配置顺了后面学习编码才能心无旁骛。Avalonia的环境配置主要围绕.NET SDK和一个趁手的IDE展开。整个过程并不复杂但对于新手特别是环境“洁癖”者或者机器上已有多个.NET版本的朋友可能会遇到一些小坑。这篇笔记我就结合自己的实操把从零开始配置Avalonia开发环境的每一步拆解清楚并附上我踩过的坑和解决方案。2. 核心工具链解析与选型在动手之前我们先理清需要哪些工具以及为什么是它们。Avalonia的生态建立在.NET之上所以核心依赖是.NET SDK。但仅仅有SDK还不够一个高效的开发环境离不开IDE或编辑器的支持。2.1 .NET SDK版本选择的艺术Avalonia与.NET版本是强绑定的。选择错误的SDK版本会导致模板无法安装或项目无法运行。当前主流选择截至2024年中Avalonia 11稳定版主要面向**.NET 8**。这是目前最推荐、生态最完善的组合。Avalonia 11带来了许多性能改进和新控件是新建项目的首选。旧版项目兼容如果你需要维护基于Avalonia 0.10.x或更早版本的项目它们可能依赖于**.NET Core 3.1**,.NET 5或.NET 6。这时你需要安装对应的SDK版本。前瞻性尝试Avalonia团队通常也会为最新的.NET预览版如.NET 9 Preview提供早期支持但这仅适用于尝鲜和测试不用于生产。我的建议对于纯粹的新手直接安装**.NET 8 SDK**。它可以向下兼容运行.NET 6/7的项目同时完美支持Avalonia 11。你可以在同一台机器上安装多个版本的SDK运行时它们会并行存在通过项目文件.csproj中的TargetFramework标签自动切换。如何安装最官方和推荐的方式是访问 Microsoft .NET 官网 下载安装程序。Windows和macOS都有安装包Linux用户则可以通过包管理器如apt、yum或dnf安装。安装完成后打开命令行CMD、PowerShell或终端输入以下命令验证dotnet --list-sdks这个命令会列出你机器上所有已安装的SDK版本。确保你看到了8.0.xxx或更高版本。2.2 开发环境Visual Studio vs VS Code这是两个主流选择各有优劣。Visual Studio 2022 (Windows/macOS)优点集成度最高对Avalonia有官方扩展Avalonia for Visual Studio提供XAML热重载、设计器预览虽然Avalonia的设计器不如WPF的成熟但一直在改进、项目模板一键创建等。对于重度.NET开发者这是最省心的选择。缺点体积庞大资源占用高。社区版免费但部分高级功能受限。安装要点安装时在“工作负载”中务必勾选“.NET 跨平台开发”。Avalonia扩展可以稍后通过VS的扩展市场搜索“Avalonia”安装。Visual Studio Code (全平台)优点轻量、快速、免费开源通过插件可以获得接近IDE的体验。搭配强大的C#插件“C# Dev Kit”和“Avalonia for VS Code”扩展也能进行高效的开发。缺点配置步骤稍多XAML设计器支持较弱主要依赖热重载和代码预览项目创建依赖命令行。适合人群喜欢轻量级工具、主要在Linux/macOS下开发或机器配置有限的开发者。我的实操心得我个人是“双修”党。在Windows上做核心UI设计和调试时用Visual Studio 2022利用其强大的调试器和相对好用的设计器。在MacBook上或需要快速编辑代码时则用VS Code响应速度更快。对于新手我建议从Visual Studio 2022开始减少环境带来的阻力先把精力集中在学习Avalonia本身。2.3 Avalonia模板项目的蓝图无论是用VS还是VS Code创建Avalonia项目都需要项目模板。这个模板通过.NET CLI工具安装。核心命令是dotnet new install Avalonia.Templates这个命令会从NuGet获取最新的Avalonia项目模板。安装成功后你可以使用dotnet new list来查看所有已安装的模板其中应该包含一系列以“Avalonia”开头的模板如avalonia.app桌面应用、avalonia.mvvmMVVM模式应用、avalonia.xplat跨平台库等。3. 详细环境配置步骤实录理论说完我们进入实战环节。我会以Windows 11 Visual Studio 2022 Community和macOS VS Code两种最典型的场景分别演示配置流程。3.1 场景一Windows Visual Studio 2022这是最“一站式”的配置方案。步骤1安装.NET 8 SDK访问.NET官网下载.NET 8 SDK安装程序并运行。安装过程基本就是“下一步”到底没有特殊选项。步骤2安装Visual Studio 2022 Community从Visual Studio官网下载安装程序。运行后在安装选择界面勾选“.NET 跨平台开发”工作负载。这个工作负载包含了开发Avalonia所需的.NET桌面开发、移动开发等基础组件。你可以点击这个工作负载右侧的“修改”确保里面包含了“.NET 8”相关的选项。然后点击安装即可。步骤3安装Avalonia for Visual Studio扩展启动Visual Studio 2022。点击顶部菜单栏的“扩展” - “管理扩展”。在弹出的窗口中点击左侧的“联机”然后在右上角的搜索框输入“Avalonia”。你应该能找到名为“Avalonia for Visual Studio 2022”的扩展由“Avalonia UI”发布。点击“下载”。下载完成后VS会提示你关闭所有窗口以安装扩展按照提示操作即可。步骤4创建你的第一个Avalonia项目重新打开VS 2022点击“创建新项目”。在搜索框输入“Avalonia”。你会看到多个模板对于新手选择“Avalonia .NET App”即可。这个模板创建的是一个使用MVVM模式的桌面应用程序结构清晰。点击“下一步”为项目命名例如HelloAvalonia选择位置解决方案名称通常会自动同步。在“其他信息”页面注意两个关键选项目标框架选择.NET 8.0。渲染模式保持默认的“DirectX”即可。这是Windows平台下性能最好的后端。其他选项如“Skia”是跨平台的2D图形库“CPU”是软件渲染。点击“创建”。步骤5运行与验证项目创建后VS会自动还原NuGet包。稍等片刻你可以直接按F5键或点击绿色的启动按钮。如果一切顺利你会看到一个带有“Welcome to Avalonia!”标题的空白窗口弹出来。恭喜你的第一个Avalonia应用运行成功了踩坑记录无法加载Avalonia设计器创建项目后你双击MainWindow.axaml文件可能发现设计器是一片空白或者提示“设计器不可用”。这是Avalonia在VS中一个常见但无害的问题。不要纠结于此。Avalonia的设计器本身还在完善中很多复杂布局和自定义控件无法预览。我们开发的主力是XAML热重载和运行时调试。确保项目能编译运行比设计器能预览更重要。你可以尝试编译一次项目CtrlShiftB有时设计器就会恢复正常。如果不行忽略它专注于代码。3.2 场景二macOS/Linux Visual Studio Code这个方案更轻量适合全平台开发者。步骤1安装.NET 8 SDKmacOS可以从官网下载pkg安装包也可以使用Homebrewbrew install --cask dotnet-sdk。Linux (Ubuntu/Debian)# 添加微软包仓库 wget https://packages.microsoft.com/config/ubuntu/22.04/packages-microsoft-prod.deb -O packages-microsoft-prod.deb sudo dpkg -i packages-microsoft-prod.deb rm packages-microsoft-prod.deb # 安装SDK sudo apt-get update sudo apt-get install -y dotnet-sdk-8.0安装后同样在终端运行dotnet --list-sdks验证。步骤2安装Visual Studio Code及必要插件从 VS Code官网 下载安装。打开VS Code进入扩展市场CtrlShiftX。安装以下两个核心扩展C# Dev Kit微软官方的C#开发套件提供智能提示、项目管理、调试等核心功能。Avalonia for Visual Studio CodeAvalonia官方扩展提供XAML语法高亮、代码片段、项目创建命令等。可选但推荐安装Avalonia XAML Previewer扩展它可以提供一个侧边栏的XAML实时预览虽然功能有限但比没有强。步骤3安装Avalonia项目模板打开VS Code的集成终端Ctrl执行命令dotnet new install Avalonia.Templates步骤4使用终端创建项目在终端中导航到你希望创建项目的目录然后执行dotnet new avalonia.app -n HelloAvalonia cd HelloAvalonia这条命令使用avalonia.app模板创建了一个名为HelloAvalonia的项目并切换到了项目目录。步骤5运行项目在项目根目录下执行dotnet run.NET CLI会自动还原依赖、编译并启动你的应用程序。你应该能看到一个窗口弹出。步骤6配置VS Code的调试环境关键步骤为了让VS Code能像IDE一样按F5调试我们需要配置启动文件。在VS Code中打开HelloAvalonia项目文件夹。点击侧边栏的“运行和调试”图标或按CtrlShiftD然后点击“创建 launch.json 文件”。在弹出的选择环境菜单中选择“.NET 5 and .NET Core”。VS Code会自动生成一个.vscode/launch.json文件。我们需要修改它。将其内容替换为以下配置{ version: 0.2.0, configurations: [ { name: Launch Avalonia App, type: coreclr, request: launch, preLaunchTask: build, program: ${workspaceFolder}/bin/Debug/net8.0/HelloAvalonia.dll, args: [], cwd: ${workspaceFolder}, stopAtEntry: false, console: internalConsole } ] }接着我们需要一个构建任务。按CtrlShiftP输入“Tasks: Configure Task”选择“Create tasks.json file from template”然后选择“.NET Core”。这会生成.vscode/tasks.json。通常默认配置即可使用。现在回到Program.cs或MainWindow.axaml.cs文件设置一个断点然后按F5。VS Code就会编译项目并在断点处暂停你可以查看变量、调用堆栈等信息了。VS Code配置心得launch.json中的program路径是关键必须指向你项目编译输出的dll文件。${workspaceFolder}代表当前项目根目录。net8.0需要根据你的目标框架调整。如果运行失败首先检查这个路径是否正确。4. 项目结构初探与关键文件解读环境配好了项目跑起来了我们趁热打铁看看这个Avalonia项目里有什么。以avalonia.app模板生成的项目为例结构如下HelloAvalonia/ ├── Assets/ # 存放图标等资源文件 ├── Views/ # 视图View层存放XAML文件 │ └── MainWindow.axaml ├── ViewModels/ # 视图模型ViewModel层存放业务逻辑类 │ └── MainWindowViewModel.cs ├── Program.cs # 应用程序入口点 ├── App.axaml # 应用程序级资源、样式定义 ├── App.axaml.cs # 应用程序启动逻辑 └── HelloAvalonia.csproj # 项目文件定义依赖和配置几个核心文件的作用Program.cs这是所有.NET应用的起点。它使用BuildAvaloniaApp启动器来配置和启动Avalonia应用。你通常不需要修改它除非有特殊的启动前配置。App.axaml和App.axaml.cs相当于WPF中的App.xaml。App.axaml用于定义应用范围的资源如样式、颜色、画笔。App.axaml.cs中的App类继承自Application它重写了OnFrameworkInitializationCompleted方法在这里指定应用程序的主窗口MainWindow。MainWindow.axaml和MainWindow.axaml.cs这是主窗口。注意后缀是.axaml这是Avalonia XAML的专用扩展名以区别于WPF的.xaml。.axaml.cs是它的代码后置文件处理窗口事件。在MVVM模式下后置文件里的代码应该非常少逻辑都放在ViewModel中。MainWindowViewModel.cs这是主窗口的视图模型。它包含了窗口需要显示的数据和命令。模板里已经实现了一个简单的INotifyPropertyChanged并有一个可点击的命令示例。.csproj项目文件打开它你会看到关键的引用PackageReference IncludeAvalonia Version11.0.10 / PackageReference IncludeAvalonia.Desktop Version11.0.10 / PackageReference IncludeAvalonia.Themes.Fluent Version11.0.10 / PackageReference IncludeAvalonia.Fonts.Inter Version11.0.10 /这定义了项目依赖的Avalonia核心包、桌面端包、Fluent Design主题包和Inter字体包。版本号可能会更新。5. 常见问题与排查技巧实录即使按照步骤操作你也可能遇到一些问题。这里汇总了我自己和社区里常见的一些“坑”。5.1 模板安装失败或找不到问题执行dotnet new install Avalonia.Templates时网络超时或报错。排查检查网络连接特别是访问NuGet源nuget.org是否通畅。可以尝试使用--nuget-source参数指定其他源或者先手动更新.NET CLIdotnet new --install。如果之前安装过旧版模板可以先卸载再安装dotnet new uninstall Avalonia.Templates。问题安装后dotnet new list里看不到Avalonia模板。排查可能是模板缓存问题。尝试运行dotnet new --debug:reinit来重新初始化模板缓存。如果还不行检查命令是否在正确的用户权限下执行。5.2 项目编译或运行失败错误“Avalonia”包无法还原或“Avalonia”包版本冲突。解决清理本地NuGet缓存在命令行运行dotnet nuget locals all --clear。删除项目根目录下的obj和bin文件夹。在项目目录下执行dotnet restore强制重新还原包。检查.csproj文件中的Avalonia包版本号确保它们一致例如都是11.0.10。有时模板生成的文件中版本号可能带有*这表示使用最新稳定版但偶尔会出问题可以手动指定一个明确的版本。错误运行时提示“无法加载DLL ‘libSkiaSharp’…”或类似的本机依赖错误。解决这是跨平台图形库SkiaSharp的本机依赖问题。Avalonia的Skia后端依赖它。确保你的项目引用了正确的Avalonia.Desktop包。对于Windows通常安装Visual Studio时自带的C运行时库就足够了。如果缺失可以安装 Microsoft Visual C Redistributable 。对于Linux可能需要安装一些额外的系统库如libfontconfig1、libfreetype6等。具体依赖可以参考SkiaSharp的官方文档。在Ubuntu上一个常见的修复命令是sudo apt-get install libfontconfig1 libfreetype6 libglib2.0-0。5.3 Visual Studio特定问题问题在VS中IntelliSense对Avalonia的XAML.axaml不工作没有代码提示。解决确保已安装并启用了“Avalonia for Visual Studio”扩展。关闭并重新打开解决方案。尝试重新构建项目CtrlShiftB。如果还不行可以尝试手动编辑项目文件.csproj在PropertyGroup里添加AvaloniaUseCompiledBindingsByDefaultfalse/AvaloniaUseCompiledBindingsByDefault然后重启VS。这有时能缓解XAML编辑器的问题。问题XAML热重载不工作。解决首先确认你是在Debug模式下运行。在VS中确保“工具”-“选项”-“Avalonia”-“XAML”下的热重载相关选项是启用的。热重载对某些结构性修改如更改类名、添加新事件处理器支持有限可能需要手动重启应用。对于简单的属性、样式修改通常是即改即现的。5.4 跨平台编译问题问题在Windows上开发的项目放到Linux上编译失败。排查行尾符确保Git配置了正确的行尾符转换core.autocrlf或者团队统一使用LF。混合的行尾符可能导致Linux上的脚本如.sh无法执行。目标运行时标识符(RID)如果你的项目文件指定了特定的RID如RuntimeIdentifierwin-x64/RuntimeIdentifier在Linux上编译就需要改为linux-x64。对于纯跨平台库可以不指定RID使用“可移植”模式。平台特定代码检查是否在代码中使用了#if WINDOWS等条件编译符号或者调用了P/Invoke导入Windows API。这些代码在Linux上需要相应的替代方案或条件编译。环境配置本身没有太多高深的技术但一个干净、正确的环境是高效学习和开发的前提。我的建议是严格按照上述步骤操作遇到问题先别慌对照错误信息结合本文的排查技巧大部分问题都能快速定位。Avalonia的社区如GitHub Discussions、Discord也非常活跃遇到棘手问题时去搜索或提问通常能得到及时的帮助。配置好环境后下一步我们就可以真正深入Avalonia的UI构建和数据绑定了。