Avalonia 源码在 IDE 中打开：Avalonia.slnx 与 Avalonia.Desktop.slnf 怎么选择？

Avalonia 源码在 IDE 中打开：Avalonia.slnx 与 Avalonia.Desktop.slnf 怎么选择？

【免费下载链接】AvaloniaDevelop Desktop, Embedded, Mobile and WebAssembly apps with C# and XAML. The future of .NET UI项目地址: https://gitcode.com/GitHub_Trending/ava/Avalonia

把 Avalonia 源码拉到本地并在 IDE 中构建时，并不是“双击解决方案文件”这么简单：仓库根目录有两个入口文件，Avalonia.slnx和Avalonia.Desktop.slnf，它们对应两种不同的构建范围。选错了，要么被迫安装一组用不到的 .NET workloads，要么想改的移动端、Web 平台项目根本没打开。本文按照仓库中 docs/build.md 的说明，讲清楚两个文件怎么选、前置环境要备齐什么、以及怎么确认构建真的跑通了。

准备：克隆仓库并确认 .NET SDK 与 IDE 版本

克隆仓库时必须带上子模块，文档给出的命令是：

git clone --recurse-submodules https://gitcode.com/GitHub_Trending/ava/Avalonia

.NET SDK 的版本以仓库根目录的 global.json 为准，其中固定了：

{ "sdk": { "version": "10.0.201", "rollForward": "latestFeature" } }

文档要求安装与该版本兼容的最新 .NET SDK，注意要下载 SDK 包而不是只有 "runtime" 的包。文档特别说明：Avalonia 并不总是使用最新的 SDK，而是硬编码使用最后一个已知兼容的版本，因为 SDK 发布有时会破坏构建，所以不要图省事装一个与global.json无关的最新版。

IDE 方面，文档支持 Visual Studio、Visual Studio Code 和 Rider，版本要求是至少支持 .NET 10，文档给出的例子是 Visual Studio 2026 或 Rider 2025.3。

按构建范围选择入口文件

docs/build.md 的 "IDEs" 一节对两个文件的定位原文是：

• Avalonia.slnx：包含完整的 Avalonia，包括 desktop、mobile 和 web。要构建这个解决方案中的所有内容，必须安装相应的 .NET workloads。
• Avalonia.Desktop.slnf：解决方案过滤器（solution filter），只打开 Avalonia 在桌面端运行所需的这部分，不需要安装额外 workloads。

对照两个文件的内容可以确认这个差异：Avalonia.slnx 中列有 Android、iOS、Browser、Headless、Windows、Linux 等平台的项目；而 Avalonia.Desktop.slnf 顶层声明了"solution": { "path": "Avalonia.slnx" }，即它本身就是对完整解决方案的一个过滤视图，项目列表只包含桌面相关的src项目、示例和测试项目，没有 Android、iOS 和 Browser 项目。

选择标准就一条：

• 只在桌面平台运行、修改代码 → 打开Avalonia.Desktop.slnf，零额外 workloads；
• 需要动移动端（Android/iOS）或 Web（Browser）项目 → 打开Avalonia.slnx，并先装好对应 workloads。

可选分支：打开完整解决方案前先安装 workloads

只有选择Avalonia.slnx时才需要这一步。文档给出的命令是：

dotnet workload install android ios tvos maccatalyst wasm-tools

两个限制条件来自文档：macOS workloads 构建 Avalonia 时不需要；在 Unix 系统上这条命令需要用 sudo 运行。

在 IDE 中打开后验证构建

打开解决方案（或过滤器）后，文档给出的验证方式是：构建并运行ControlCatalog.Desktop项目，看到示例应用即可确认源码环境可用。等价的命令行路径为：

cd samples/ControlCatalog.Desktop dotnet restore dotnet run

文档原文为cd samples\ControlCatalog.Desktop，是 Windows 风格的反斜杠写法；在 Unix 系统上应使用正斜杠路径。窗口中启动 ControlCatalog 示例应用，即说明从打开入口文件到构建运行的链路已走通。

IDE 内构建的两个已知问题

报错 MSB4062 GenerateAvaloniaResourcesTask

文档说明：如果在 IDE 内构建时遇到这个错误，手动构建一次Avalonia.Build.Tasks项目即可；另一个替代做法是用 Nuke 构建一次解决方案。注意Avalonia.Build.Tasks也在Avalonia.Desktop.slnf的项目列表中，用过滤器打开时可以直接在列表里找到它并构建。

更新本地仓库后构建异常

文档要求更新本地仓库后确保子模块同步，以避免各类问题：

git submodule update --init --recursive

如果要使用 Nuke 构建完整解决方案（包括作为 MSB4062 的修复手段之一），文档给出的命令是：

dotnet tool install --global Nuke.GlobalTool nuke --target Compile --configuration Release

macOS 专属：构建原生库需要 Xcode

文档单列了一节说明：在 macOS 上，构建过程需要 Xcode 来构建原生库。安装 Xcode 后，执行根目录构建脚本的CompileNative任务，它会构建头文件和库并放到 .NET 在编译和运行期能找到的位置：

./build.sh CompileNative

这是构建文档中仅针对 macOS 的步骤，按你的操作系统决定是否执行即可。

到这里，入口文件的选择不只是一个“点哪个文件”的问题：它决定了你要不要装 workloads、IDE 里能看到哪些平台项目。桌面场景下用Avalonia.Desktop.slnf打开、装好global.json指定的 SDK、跑通ControlCatalog.Desktop，就是文档定义的完整可用状态。

【免费下载链接】AvaloniaDevelop Desktop, Embedded, Mobile and WebAssembly apps with C# and XAML. The future of .NET UI项目地址: https://gitcode.com/GitHub_Trending/ava/Avalonia