mirror of
https://github.com/wwiinnddyy/LanMountainDesktop.git
synced 2026-06-25 03:04:26 +08:00
feat.文档更新
This commit is contained in:
lincube
156
docs/00-快速开始/01-项目介绍.md
Normal file
156
docs/00-快速开始/01-项目介绍.md
Normal file
@@ -0,0 +1,156 @@
|
||||
# 项目介绍
|
||||
|
||||
## 什么是阑山桌面
|
||||
|
||||
**LanMountainDesktop（阑山桌面）** 是一个基于 .NET 和 Avalonia UI 的模块化桌面定制平台，旨在为用户提供高度可定制的桌面体验。
|
||||
|
||||
### 核心特性
|
||||
|
||||
#### 🧩 插件系统
|
||||
- **进程内插件** - 当前稳定的插件运行模式
|
||||
- **进程隔离插件** - 未来支持的隔离模式（规划中）
|
||||
- **插件 SDK** - 完整的插件开发工具包
|
||||
- **插件市场** - 应用内插件浏览和安装
|
||||
|
||||
#### 🎨 桌面组件（Widget）
|
||||
- **可视化编辑** - 拖拽式布局编辑
|
||||
- **多种组件** - 时钟、天气、日历、倒计时等
|
||||
- **自定义组件** - 通过插件扩展新组件
|
||||
- **主题支持** - 亮色/暗色模式自适应
|
||||
|
||||
#### 🚀 Air APP 系统
|
||||
- **独立应用** - 在桌面环境中运行的独立窗口应用
|
||||
- **生命周期管理** - 统一的应用启动、激活和清理
|
||||
- **窗口模式** - 标准、无边框、全屏、工具窗口
|
||||
- **IPC 通信** - 与桌面宿主的双向通信
|
||||
|
||||
#### ⚙️ 设置系统
|
||||
- **分域管理** - 按功能模块组织设置
|
||||
- **持久化** - 自动保存到本地
|
||||
- **插件集成** - 插件可注册自己的设置页
|
||||
|
||||
#### 🔄 更新系统
|
||||
- **增量更新** - 只下载变更文件，节省带宽
|
||||
- **原子化更新** - 保证更新完整性，失败自动回滚
|
||||
- **多版本管理** - 支持版本共存和回退
|
||||
- **签名验证** - RSA 签名确保安全性
|
||||
|
||||
## 技术架构
|
||||
|
||||
### 核心技术栈
|
||||
|
||||
| 技术 | 版本 | 用途 |
|
||||
|------|------|------|
|
||||
| .NET | 10.0 | 应用框架 |
|
||||
| Avalonia UI | 12.x | 跨平台 UI 框架 |
|
||||
| FluentAvalonia | 2.x | Fluent Design 控件 |
|
||||
| CommunityToolkit.Mvvm | 8.x | MVVM 框架 |
|
||||
| VeloPack | 最新 | 应用更新系统 |
|
||||
| dotnetCampus.Ipc | 最新 | 进程间通信 |
|
||||
|
||||
### 项目结构
|
||||
|
||||
```
|
||||
LanMountainDesktop/
|
||||
├── LanMountainDesktop/ # 主桌面宿主应用
|
||||
├── LanMountainDesktop.Launcher/ # 启动器（OOBE、Splash、版本管理）
|
||||
├── LanMountainDesktop.AirAppRuntime/ # Air APP 运行时容器
|
||||
├── LanMountainDesktop.AirAppHost/ # Air APP 渲染进程
|
||||
├── LanMountainDesktop.PluginSdk/ # 插件 SDK
|
||||
├── LanMountainDesktop.Shared.Contracts/ # 共享契约类型
|
||||
├── LanMountainDesktop.Settings.Core/ # 设置系统
|
||||
├── LanMountainDesktop.Appearance/ # 主题和外观
|
||||
├── LanMountainDesktop.DesktopComponents.Runtime/# 组件运行时
|
||||
└── LanMountainDesktop.PluginIsolation.*/ # 插件隔离（未来）
|
||||
```
|
||||
|
||||
### 启动流程
|
||||
|
||||
```
|
||||
用户启动 Launcher.exe
|
||||
↓
|
||||
首次启动 → OOBE 引导
|
||||
↓
|
||||
显示 Splash 启动动画
|
||||
↓
|
||||
预启动 AirAppRuntime（框架依赖 JIT 进程）
|
||||
↓
|
||||
扫描 app-* 目录，选择最佳版本
|
||||
↓
|
||||
启动 LanMountainDesktop.exe（主程序）
|
||||
↓
|
||||
初始化日志、遥测、Host 生命周期
|
||||
↓
|
||||
加载主题、语言、设置
|
||||
↓
|
||||
初始化桌面壳层、主窗口、托盘
|
||||
↓
|
||||
加载插件、注册组件
|
||||
↓
|
||||
桌面就绪
|
||||
```
|
||||
|
||||
## 应用场景
|
||||
|
||||
### 个人用户
|
||||
- **桌面定制** - 打造个性化的桌面环境
|
||||
- **效率工具** - 快速访问常用功能和信息
|
||||
- **信息聚合** - 在桌面上展示天气、日历、待办等
|
||||
|
||||
### 开发者
|
||||
- **插件开发** - 为桌面扩展新功能
|
||||
- **Air APP 开发** - 创建独立的桌面应用
|
||||
- **组件开发** - 设计自定义桌面组件
|
||||
|
||||
### 企业用户
|
||||
- **定制部署** - 企业专用的桌面环境
|
||||
- **信息看板** - 展示企业数据和通知
|
||||
- **工作流集成** - 集成企业工作流工具
|
||||
|
||||
## 版本与支持
|
||||
|
||||
### 当前版本
|
||||
- **稳定版**: 查看 [GitHub Releases](https://github.com/HelloWRC/LanMountainDesktop/releases)
|
||||
- **预览版**: 通过更新频道切换到 Preview
|
||||
|
||||
### 平台支持
|
||||
- ✅ **Windows 10/11** - 完整支持
|
||||
- 🚧 **Linux** - 计划支持
|
||||
- 🚧 **macOS** - 计划支持
|
||||
|
||||
### 系统要求
|
||||
- **操作系统**: Windows 10 1809 或更高版本
|
||||
- **.NET Runtime**: 自动包含，无需单独安装
|
||||
- **内存**: 建议 4GB 或更高
|
||||
- **磁盘**: 安装需要约 200MB 空间
|
||||
|
||||
## 开发理念
|
||||
|
||||
### 模块化设计
|
||||
所有功能通过插件和组件实现，核心保持精简。
|
||||
|
||||
### 开放生态
|
||||
鼓励社区开发插件和组件，共建生态系统。
|
||||
|
||||
### 稳定可靠
|
||||
原子化更新、版本回退、进程隔离等机制保证系统稳定。
|
||||
|
||||
### 性能优先
|
||||
增量更新、延迟加载、异步渲染等优化确保流畅体验。
|
||||
|
||||
## 开源协议
|
||||
|
||||
本项目采用 [MIT License](https://github.com/HelloWRC/LanMountainDesktop/blob/main/LICENSE) 开源协议。
|
||||
|
||||
## 社区与贡献
|
||||
|
||||
- **GitHub**: https://github.com/HelloWRC/LanMountainDesktop
|
||||
- **Issues**: 报告 Bug 和功能建议
|
||||
- **Discussions**: 技术讨论和问答
|
||||
- **Pull Requests**: 欢迎贡献代码和文档
|
||||
|
||||
## 下一步
|
||||
|
||||
- [快速安装](02-快速安装.md) - 安装阑山桌面
|
||||
- [开发环境配置](03-开发环境配置.md) - 配置开发环境
|
||||
- [插件开发快速开始](../01-插件开发/01-快速开始/01-环境准备.md) - 开始开发插件
|
||||
277
docs/00-快速开始/02-快速安装.md
Normal file
277
docs/00-快速开始/02-快速安装.md
Normal file
@@ -0,0 +1,277 @@
|
||||
# 快速安装
|
||||
|
||||
本指南将帮助你快速安装和运行阑山桌面。
|
||||
|
||||
## 安装方式
|
||||
|
||||
### 方式一：使用安装包（推荐）
|
||||
|
||||
#### 下载安装包
|
||||
|
||||
访问 [GitHub Releases](https://github.com/HelloWRC/LanMountainDesktop/releases) 页面，下载最新版本的安装包：
|
||||
|
||||
- **Windows x64**: `LanMountainDesktop-Setup-{version}-x64.exe`
|
||||
|
||||
#### 运行安装程序
|
||||
|
||||
1. 双击下载的安装包
|
||||
2. 按照安装向导提示完成安装
|
||||
3. 安装完成后，启动器会自动运行
|
||||
|
||||
#### 首次启动 (OOBE)
|
||||
|
||||
首次启动时会显示欢迎页面：
|
||||
|
||||
1. **欢迎页** - 项目介绍和基本说明
|
||||
2. **权限确认** - 了解应用所需的权限
|
||||
3. **基础设置** - 选择主题、语言等
|
||||
4. **完成** - 开始使用阑山桌面
|
||||
|
||||
### 方式二：便携版
|
||||
|
||||
#### 下载便携包
|
||||
|
||||
从 [GitHub Releases](https://github.com/HelloWRC/LanMountainDesktop/releases) 下载：
|
||||
|
||||
- **Windows x64**: `LanMountainDesktop-Portable-{version}-x64.zip`
|
||||
|
||||
#### 解压并运行
|
||||
|
||||
```powershell
|
||||
# 解压到目标目录
|
||||
Expand-Archive -Path LanMountainDesktop-Portable-1.0.0-x64.zip -DestinationPath C:\LanMountainDesktop
|
||||
|
||||
# 进入目录
|
||||
cd C:\LanMountainDesktop
|
||||
|
||||
# 启动应用
|
||||
.\LanMountainDesktop.Launcher.exe
|
||||
```
|
||||
|
||||
#### 便携版特点
|
||||
|
||||
- ✅ 无需安装，解压即用
|
||||
- ✅ 数据存储在程序目录
|
||||
- ✅ 适合 U 盘或多机器同步使用
|
||||
- ⚠️ 需要手动创建快捷方式
|
||||
- ⚠️ 不会自动添加到开始菜单
|
||||
|
||||
## 目录结构
|
||||
|
||||
### 安装版目录结构
|
||||
|
||||
```
|
||||
安装根目录/
|
||||
├── LanMountainDesktop.Launcher.exe # 启动器（唯一入口）
|
||||
├── app-1.0.0/ # 版本目录
|
||||
│ ├── .current # 当前版本标记
|
||||
│ ├── LanMountainDesktop.exe # 主程序
|
||||
│ ├── *.dll # 依赖库
|
||||
│ └── ...
|
||||
├── LanMountainDesktop.AirAppRuntime.exe # Air APP 运行时
|
||||
├── .Launcher/ # 启动器数据
|
||||
│ ├── state/ # OOBE 状态
|
||||
│ └── update/ # 更新缓存
|
||||
└── unins000.exe # 卸载程序
|
||||
```
|
||||
|
||||
### 用户数据目录
|
||||
|
||||
```
|
||||
%LOCALAPPDATA%\LanMountainDesktop\
|
||||
├── settings/ # 设置文件
|
||||
├── plugins/ # 已安装插件
|
||||
├── logs/ # 日志文件
|
||||
├── cache/ # 缓存数据
|
||||
└── telemetry/ # 遥测数据（可选）
|
||||
```
|
||||
|
||||
### 便携版目录结构
|
||||
|
||||
便携版的用户数据存储在程序目录的 `Data/` 文件夹下：
|
||||
|
||||
```
|
||||
LanMountainDesktop/
|
||||
├── LanMountainDesktop.Launcher.exe
|
||||
├── app-1.0.0/
|
||||
├── Data/ # 便携数据目录
|
||||
│ ├── settings/
|
||||
│ ├── plugins/
|
||||
│ ├── logs/
|
||||
│ └── cache/
|
||||
└── ...
|
||||
```
|
||||
|
||||
## 启动选项
|
||||
|
||||
### 正常启动
|
||||
|
||||
```powershell
|
||||
# 双击启动器
|
||||
.\LanMountainDesktop.Launcher.exe
|
||||
|
||||
# 或从开始菜单启动
|
||||
```
|
||||
|
||||
### 命令行选项
|
||||
|
||||
```powershell
|
||||
# 显示版本信息
|
||||
.\LanMountainDesktop.Launcher.exe --version
|
||||
|
||||
# 显示帮助信息
|
||||
.\LanMountainDesktop.Launcher.exe --help
|
||||
|
||||
# 重置 OOBE 状态（重新显示欢迎页）
|
||||
.\LanMountainDesktop.Launcher.exe --reset-oobe
|
||||
|
||||
# 启动到指定版本
|
||||
.\LanMountainDesktop.Launcher.exe --version 1.0.0
|
||||
|
||||
# 安装插件（本地维护命令）
|
||||
.\LanMountainDesktop.Launcher.exe plugin install path\to\plugin.laapp
|
||||
|
||||
# 应用插件更新队列（本地维护命令）
|
||||
.\LanMountainDesktop.Launcher.exe plugin update
|
||||
```
|
||||
|
||||
## 验证安装
|
||||
|
||||
### 检查应用状态
|
||||
|
||||
启动后，你应该看到：
|
||||
|
||||
1. **桌面组件** - 默认的时钟或其他组件显示在桌面上
|
||||
2. **系统托盘图标** - 阑山桌面的托盘图标
|
||||
3. **主窗口** - 可通过托盘图标打开
|
||||
|
||||
### 检查日志
|
||||
|
||||
如果遇到问题，可以查看日志：
|
||||
|
||||
```powershell
|
||||
# 打开日志目录
|
||||
explorer %LOCALAPPDATA%\LanMountainDesktop\logs
|
||||
|
||||
# 查看最新日志
|
||||
Get-Content %LOCALAPPDATA%\LanMountainDesktop\logs\latest.log -Tail 50
|
||||
```
|
||||
|
||||
### 检查版本信息
|
||||
|
||||
1. 右键点击托盘图标
|
||||
2. 选择"关于"或"设置"
|
||||
3. 查看版本号和构建信息
|
||||
|
||||
## 常见问题
|
||||
|
||||
### 安装失败
|
||||
|
||||
**问题**: 安装程序报错或无法完成安装
|
||||
|
||||
**解决方案**:
|
||||
1. 确认 Windows 版本 ≥ Windows 10 1809
|
||||
2. 以管理员身份运行安装程序
|
||||
3. 关闭杀毒软件和防火墙
|
||||
4. 检查磁盘空间是否充足（≥ 500MB）
|
||||
5. 查看安装日志：`%TEMP%\LanMountainDesktop-Setup.log`
|
||||
|
||||
### 启动失败
|
||||
|
||||
**问题**: 双击启动器没有反应
|
||||
|
||||
**解决方案**:
|
||||
1. 检查进程管理器是否已有实例运行
|
||||
2. 查看日志文件：`%LOCALAPPDATA%\LanMountainDesktop\logs\latest.log`
|
||||
3. 尝试以管理员身份运行
|
||||
4. 检查是否有其他应用占用端口或资源
|
||||
|
||||
### OOBE 无法显示
|
||||
|
||||
**问题**: 首次启动没有显示欢迎页面
|
||||
|
||||
**解决方案**:
|
||||
1. 删除 OOBE 状态文件：
|
||||
```powershell
|
||||
Remove-Item -Path "$env:LOCALAPPDATA\LanMountainDesktop\.launcher\state\oobe-state.json" -Force
|
||||
```
|
||||
2. 重新启动应用
|
||||
|
||||
### 组件不显示
|
||||
|
||||
**问题**: 桌面上看不到任何组件
|
||||
|
||||
**解决方案**:
|
||||
1. 右键点击桌面空白处
|
||||
2. 选择"添加组件"
|
||||
3. 选择一个组件添加到桌面
|
||||
4. 检查组件是否被其他窗口遮挡
|
||||
5. 确认桌面图层设置正确（设置 → 桌面 → 图层模式）
|
||||
|
||||
## 卸载应用
|
||||
|
||||
### 使用控制面板
|
||||
|
||||
1. 打开"设置" → "应用" → "已安装的应用"
|
||||
2. 找到"LanMountainDesktop"
|
||||
3. 点击"卸载"按钮
|
||||
4. 按照向导完成卸载
|
||||
|
||||
### 使用卸载程序
|
||||
|
||||
```powershell
|
||||
# 运行卸载程序
|
||||
.\unins000.exe
|
||||
```
|
||||
|
||||
### 清理残留数据
|
||||
|
||||
卸载后，用户数据不会自动删除。如需彻底清理：
|
||||
|
||||
```powershell
|
||||
# 删除用户数据目录
|
||||
Remove-Item -Path "$env:LOCALAPPDATA\LanMountainDesktop" -Recurse -Force
|
||||
|
||||
# 删除 Launcher 状态
|
||||
Remove-Item -Path "$env:LOCALAPPDATA\LanMountainDesktop\.launcher" -Recurse -Force
|
||||
|
||||
# 删除缓存（如果存在）
|
||||
Remove-Item -Path "$env:TEMP\LanMountainDesktop" -Recurse -Force -ErrorAction SilentlyContinue
|
||||
```
|
||||
|
||||
## 更新应用
|
||||
|
||||
### 自动更新（推荐）
|
||||
|
||||
阑山桌面支持自动更新：
|
||||
|
||||
1. 应用会在后台检查更新
|
||||
2. 发现新版本时会提示下载
|
||||
3. 下载完成后重启应用自动安装
|
||||
4. 支持增量更新，只下载变更文件
|
||||
|
||||
### 手动更新
|
||||
|
||||
如果需要手动更新：
|
||||
|
||||
1. 访问 [GitHub Releases](https://github.com/HelloWRC/LanMountainDesktop/releases)
|
||||
2. 下载最新版本的安装包
|
||||
3. 运行安装包，选择"覆盖安装"
|
||||
4. 安装完成后启动新版本
|
||||
|
||||
### 更新频道
|
||||
|
||||
可以在设置中切换更新频道：
|
||||
|
||||
- **Stable（稳定版）**: 只接收正式发布的版本
|
||||
- **Preview（预览版）**: 接收所有版本，包括预发布版本
|
||||
|
||||
```
|
||||
设置 → 更新 → 更新频道 → 选择频道
|
||||
```
|
||||
|
||||
## 下一步
|
||||
|
||||
- [开发环境配置](03-开发环境配置.md) - 配置开发环境
|
||||
- [插件开发快速开始](../01-插件开发/01-快速开始/01-环境准备.md) - 开始开发插件
|
||||
- [使用教程](04-基础使用.md) - 了解基本使用方法
|
||||
380
docs/00-快速开始/03-开发环境配置.md
Normal file
380
docs/00-快速开始/03-开发环境配置.md
Normal file
@@ -0,0 +1,380 @@
|
||||
# 开发环境配置
|
||||
|
||||
本指南将帮助你配置阑山桌面的开发环境，以便进行插件开发、组件开发或贡献核心代码。
|
||||
|
||||
## 系统要求
|
||||
|
||||
### 操作系统
|
||||
- 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) - 贡献代码到项目
|
||||
Reference in New Issue
Block a user