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

# 开发环境配置

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

## 系统要求

### 操作系统
- Windows 10 1809 或更高版本（推荐 Windows 11）
- Linux（实验性支持）
- macOS（计划支持）

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

## 必需工具

### 1. .NET SDK

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

#### 下载并安装

访问 [.NET 官网](https://dotnet.microsoft.com/download/dotnet/10.0) 下载并安装 .NET 10 SDK。

#### 验证安装

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

### 2. IDE 选择

#### 选项 A: Visual Studio 2022（推荐）

**下载**: [Visual Studio 2022](https://visualstudio.microsoft.com/vs/)

**工作负载**:
- ✅ .NET 桌面开发
- ✅ ASP.NET 和 Web 开发（用于调试工具）
- ✅ .NET 跨平台开发

**推荐扩展**:
- Avalonia for Visual Studio
- GitHub Copilot（可选）
- ReSharper 或 Rider（可选）

#### 选项 B: JetBrains Rider

**下载**: [JetBrains Rider](https://www.jetbrains.com/rider/)

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

#### 选项 C: Visual Studio Code

**下载**: [Visual Studio Code](https://code.visualstudio.com/)

**必需扩展**:
- C# Dev Kit
- Avalonia for VSCode
- .NET Extension Pack

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

### 3. Git

#### 下载并安装

- **Windows**: [Git for Windows](https://git-scm.com/download/win)
- **Linux**: `sudo apt install git` 或 `sudo dnf install git`
- **macOS**: `brew install git`

#### 验证安装

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

#### 配置 Git

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

## 可选工具

### 1. PowerShell 7+

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

```powershell
# 安装 PowerShell 7
winget install Microsoft.PowerShell
```

### 2. Windows Terminal

更好的终端体验。

```powershell
# 安装 Windows Terminal
winget install Microsoft.WindowsTerminal
```

### 3. Avalonia UI 预览器

#### Visual Studio 扩展

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

#### JetBrains Rider

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

## 克隆仓库

### 从 GitHub 克隆

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

# 进入目录
cd LanMountainDesktop

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

### 初始化子模块

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

```powershell
git submodule update --init --recursive
```

## 构建项目

### 还原依赖

```powershell
# 还原 NuGet 包
dotnet restore
```

### 构建解决方案

```powershell
# 构建整个解决方案
dotnet build

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

### 运行应用

```powershell
# 方式 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/` | 文档 |

## 安装插件模板

### 安装官方模板

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

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

### 创建测试插件

```powershell
# 创建新插件
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`：

```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
    }
  ]
}
```

## 运行测试

### 运行所有测试

```powershell
dotnet test
```

### 运行特定测试项目

```powershell
dotnet test LanMountainDesktop.Tests/LanMountainDesktop.Tests.csproj
```

### 带覆盖率的测试

```powershell
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`

**解决方案**:
```powershell
# 检查 SDK 版本
dotnet --list-sdks

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

### NuGet 包还原失败

**问题**: `error NU1101: Unable to find package`

**解决方案**:
```powershell
# 清理 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

## 下一步

- [插件开发快速开始](../01-插件开发/01-快速开始/01-环境准备.md) - 开始开发插件
- [整体架构](../04-架构与实现/01-整体架构.md) - 了解系统架构
- [贡献指南](05-贡献指南.md) - 贡献代码到项目