LanMountainDesktop/docs/00-快速开始/03-开发环境配置.md

开发环境配置

本指南将帮助你配置阑山桌面的开发环境，以便进行插件开发、组件开发或贡献核心代码。

系统要求

操作系统

• Windows 10 1809 或更高版本（推荐 Windows 11）
• Linux（实验性支持）
• macOS（计划支持）

硬件要求

• CPU: 双核或更高
• 内存: 8GB 或更高（推荐 16GB）
• 磁盘: 至少 10GB 可用空间
• 显示器: 1920x1080 或更高分辨率

必需工具

1. .NET SDK

阑山桌面基于 .NET 10，需要安装对应的 SDK。

下载并安装

访问 .NET 官网 下载并安装 .NET 10 SDK。

验证安装

dotnet --version
# 应输出: 10.0.x

2. IDE 选择

选项 A: Visual Studio 2022（推荐）

下载: Visual Studio 2022

工作负载:

• ✅ .NET 桌面开发
• ✅ ASP.NET 和 Web 开发（用于调试工具）
• ✅ .NET 跨平台开发

推荐扩展:

• Avalonia for Visual Studio
• GitHub Copilot（可选）
• ReSharper 或 Rider（可选）

选项 B: JetBrains Rider

下载: JetBrains Rider

优势:

• 优秀的代码分析和重构功能
• 内置 Avalonia 支持
• 跨平台支持

选项 C: Visual Studio Code

下载: Visual Studio Code

必需扩展:

• C# Dev Kit
• Avalonia for VSCode
• .NET Extension Pack

配置:

// .vscode/settings.json
{
  "dotnet.defaultSolution": "LanMountainDesktop.sln",
  "omnisharp.enableRoslynAnalyzers": true,
  "omnisharp.enableEditorConfigSupport": true
}

3. Git

下载并安装

• Windows: Git for Windows
• Linux: sudo apt install git 或 sudo dnf install git
• macOS: brew install git

验证安装

git --version
# 应输出: git version 2.x.x

配置 Git

git config --global user.name "你的名字"
git config --global user.email "your.email@example.com"

可选工具

1. PowerShell 7+

用于运行构建和发布脚本。

# 安装 PowerShell 7
winget install Microsoft.PowerShell

2. Windows Terminal

更好的终端体验。

# 安装 Windows Terminal
winget install Microsoft.WindowsTerminal

3. Avalonia UI 预览器

Visual Studio 扩展

在 Visual Studio 中安装"Avalonia for Visual Studio"扩展，可以实时预览 AXAML 文件。

JetBrains Rider

Rider 内置了 Avalonia 预览器，无需额外安装。

克隆仓库

从 GitHub 克隆

# 克隆主仓库
git clone https://github.com/HelloWRC/LanMountainDesktop.git

# 进入目录
cd LanMountainDesktop

# 切换到开发分支（如果有）
git checkout develop

初始化子模块

如果项目使用了 Git 子模块：

git submodule update --init --recursive

构建项目

还原依赖

# 还原 NuGet 包
dotnet restore

构建解决方案

# 构建整个解决方案
dotnet build

# 或者构建特定项目
dotnet build LanMountainDesktop/LanMountainDesktop.csproj

运行应用

# 方式 1: 通过 Launcher 启动（推荐）
dotnet run --project LanMountainDesktop.Launcher

# 方式 2: 直接启动主程序（开发模式）
dotnet run --project LanMountainDesktop

# 方式 3: 使用 Visual Studio
# 按 F5 启动调试

项目结构

解决方案结构

LanMountainDesktop.sln
├── LanMountainDesktop                    # 主程序
├── LanMountainDesktop.Launcher           # 启动器
├── LanMountainDesktop.PluginSdk          # 插件 SDK
├── LanMountainDesktop.AirAppRuntime      # Air APP 运行时
├── LanMountainDesktop.AirAppHost         # Air APP 宿主
├── LanMountainDesktop.Shared.Contracts   # 共享契约
└── LanMountainDesktop.Tests              # 测试项目

重要目录

目录	说明
LanMountainDesktop/Views/	UI 视图文件 (.axaml)
LanMountainDesktop/ViewModels/	视图模型
LanMountainDesktop/Services/	业务服务
LanMountainDesktop/ComponentSystem/	组件系统
LanMountainDesktop/plugins/	插件运行时
scripts/	构建和发布脚本
docs/	文档

安装插件模板

安装官方模板

# 安装插件模板
dotnet new install LanMountainDesktop.PluginTemplate

# 验证安装
dotnet new list | Select-String "lmd"

创建测试插件

# 创建新插件
dotnet new lmd-plugin -n MyTestPlugin

# 进入插件目录
cd MyTestPlugin

# 构建插件
dotnet build

# 打包为 .laapp
dotnet publish -c Release

调试配置

Visual Studio 调试配置

1. 右键点击"LanMountainDesktop.Launcher"项目
2. 选择"设为启动项目"
3. 按 F5 开始调试

多项目调试

如果需要同时调试 Launcher 和 Host：

1. 右键点击解决方案
2. 选择"属性" → "启动项目"
3. 选择"多个启动项目"
4. 设置"LanMountainDesktop.Launcher"为"启动"

VSCode 调试配置

创建 .vscode/launch.json：

{
  "version": "0.2.0",
  "configurations": [
    {
      "name": "Launch Launcher",
      "type": "coreclr",
      "request": "launch",
      "preLaunchTask": "build",
      "program": "${workspaceFolder}/LanMountainDesktop.Launcher/bin/Debug/net10.0/LanMountainDesktop.Launcher.exe",
      "args": [],
      "cwd": "${workspaceFolder}/LanMountainDesktop.Launcher/bin/Debug/net10.0",
      "console": "internalConsole",
      "stopAtEntry": false
    },
    {
      "name": "Launch Host (Direct)",
      "type": "coreclr",
      "request": "launch",
      "preLaunchTask": "build",
      "program": "${workspaceFolder}/LanMountainDesktop/bin/Debug/net10.0/LanMountainDesktop.exe",
      "args": [],
      "cwd": "${workspaceFolder}/LanMountainDesktop/bin/Debug/net10.0",
      "console": "internalConsole",
      "stopAtEntry": false
    }
  ]
}

运行测试

运行所有测试

dotnet test

运行特定测试项目

dotnet test LanMountainDesktop.Tests/LanMountainDesktop.Tests.csproj

带覆盖率的测试

dotnet test --collect:"XPlat Code Coverage"

代码规范

EditorConfig

项目包含 .editorconfig 文件，自动配置代码风格。确保你的 IDE 支持 EditorConfig。

代码分析

项目启用了 Roslyn 分析器，编译时会显示代码质量警告。

推荐的编码规范

• 使用 nullable 引用类型
• 遵循 C# 命名约定
• 优先使用 async/await 而不是 Task.Wait()
• 为公共 API 编写 XML 文档注释

常见问题

编译错误: SDK 版本不匹配

问题: error NETSDK1045: The current .NET SDK does not support targeting .NET 10.0

解决方案:

# 检查 SDK 版本
dotnet --list-sdks

# 如果没有 10.0.x，请安装 .NET 10 SDK

NuGet 包还原失败

问题: error NU1101: Unable to find package

解决方案:

# 清理 NuGet 缓存
dotnet nuget locals all --clear

# 重新还原
dotnet restore

Avalonia 预览器不工作

问题: AXAML 文件无法预览

解决方案:

1. 确保安装了 Avalonia 扩展
2. 重启 IDE
3. 检查项目是否正确引用了 Avalonia 包
4. 尝试清理并重新构建项目

调试时无法附加进程

问题: 无法附加到 LanMountainDesktop 进程

解决方案:

1. 确保没有其他实例正在运行
2. 以管理员身份运行 IDE
3. 检查防火墙设置
4. 使用"直接启动 Host"模式而不是通过 Launcher

下一步

• 插件开发快速开始 - 开始开发插件
• 整体架构 - 了解系统架构
• 贡献指南 - 贡献代码到项目