入门指南

让我们开始使用 Avalonia。本指南将带您完成安装 Avalonia 并在集成开发环境 (IDE) 中启动第一个项目的过程。

先决条件

您必须已安装：

.NET（8.0 或更高版本，截至 2025 年 10 月）
您选择的 IDE（我们推荐 JetBrains Rider 或 Visual Studio）

安装 .NET

从 .NET 官网下载，然后按照安装说明进行操作。

选择 IDE

Avalonia 在 Visual Studio 或 JetBrains Rider 中效果最佳。

Visual Studio Code 也受支持，但由于功能较为有限，我们不推荐使用。

Rider
Visual Studio
Visual Studio Code

如果您使用 macOS 或 Linux，我们推荐使用 JetBrains Rider。JetBrains Rider 在这些操作系统上提供完整、成熟的开发体验，包括对 XAML 的内置支持。

建议安装第三方插件 AvaloniaRider，该插件可在您工作时实时预览 XAML。

安装 AvaloniaRider：

在 JetBrains Rider 中，转到设置 → 插件。
转到市场选项卡。
在搜索栏中输入"AvaloniaRider"。
点击安装。
按照任何其他安装说明进行操作。您可能需要关闭并重新打开 JetBrains Rider 以完成安装。

有关使用 XAML 预览器的更多信息，请参阅 XAML 预览器页面。

安装 Avalonia 模板

根据您使用的 IDE，您可能已经安装了 Avalonia 模板。使用 Avalonia for Visual Studio 扩展的 Visual Studio 就是这种情况。

您可以运行此命令来检查有哪些可用的 .NET 模板：

dotnet new list

在其他 .NET 模板中查找这些 Avalonia 模板：

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

如果您在列表中没有看到这些模板，可以运行此命令来安装它们：

dotnet new install Avalonia.Templates

检查输出。您应该会看到这些模板已安装：

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/Web/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

安装故障排除

.NET 不是已识别的程序

首先，确保已安装 .NET SDK。运行此命令：

dotnet --list-sdks

如果正确安装了 .NET SDK，将返回类似以下的输出：

8.0.202 [C:\Program Files\dotnet\sdk]

如果终端继续报告缺少 .NET，请尝试重新启动终端。

找不到 `Avalonia.Templates` 包

确保 NuGet 已正确设置。运行此命令：

dotnet nuget list source

检查输出是否显示以下内容作为已注册的源：

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

如果未列出此源，请使用此命令添加它：

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

如果即使 NuGet 已列为已注册源，包安装仍然失败，请检查您的网络连接或防火墙设置。

创建您的第一个项目

您的第一个项目将使用 MVVM 模板。

Rider
Visual Studio
Visual Studio Code
命令行

在 Rider 启动屏幕上，选择新建解决方案。
在侧边栏中，向下滚动到"自定义模板"。选择 Avalonia .NET MVVM App。
将您的解决方案命名为"GetStartedApp"。
点击创建。

在命令行中运行此命令：

dotnet new avalonia.mvvm -o GetStartedApp

检查您的设备上是否有一个名为 GetStartedApp 的新文件夹，其中包含新的项目文件。

运行您的项目

Rider
Visual Studio
Visual Studio Code
命令行

点击顶部工具栏中的运行。

解决方案将构建并在新窗口中运行您的应用程序。默认情况下，会显示字符串"Welcome to Avalonia!"

导航到包含您的 GetStartedApp 项目的目录。
运行命令 dotnet run。

解决方案将构建并在新窗口中运行您的应用程序。默认情况下，会显示字符串"Welcome to Avalonia!"

后续步骤

您现在已经在设备上安装了 Avalonia，并知道如何创建和运行 Avalonia 项目。

您可以立即开始开发应用程序。

或者，如果想要一个简短的教程，构建一个简单的应用程序，介绍 Avalonia 中的基本概念和功能，请继续阅读下一页：

先决条件​

安装 .NET​

选择 IDE​

安装 Avalonia 模板​

安装故障排除​

.NET 不是已识别的程序​

找不到 Avalonia.Templates 包​

创建您的第一个项目​

运行您的项目​

后续步骤​