跳到主要内容

入门指南

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

先决条件​

您必须已安装：

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

安装 .NET​

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

选择 IDE​

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

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

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

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

安装 AvaloniaRider：

  1. 在 JetBrains Rider 中，转到设置 → 插件。
  2. 转到市场选项卡。
  3. 在搜索栏中输入"AvaloniaRider"。
  4. 点击安装。
  5. 按照任何其他安装说明进行操作。您可能需要关闭并重新打开 JetBrains Rider 以完成安装。
显示如何在 Rider 中下载 AvaloniaRider 扩展的屏幕截图。

有关使用 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.app                [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 模板。

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

运行您的项目​

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

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

在窗口中运行的默认 Avalonia 应用程序的屏幕截图。

后续步骤​

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

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

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