LanMountainDesktop/docs/Plugins develop/01-快速开始/02-三分钟创建第一个插件.md

# 02-三分钟创建第一个插件

本指南将帮助你在三分钟内创建并运行你的第一个阑山桌面插件。让我们开始吧！

---

## 🎯 目标

完成本指南后，你将：
- ✅ 创建一个可运行的插件项目
- ✅ 在宿主中成功加载插件
- ✅ 在插件列表中看到你的插件

---

## ⚡ 步骤一：创建项目（30秒）

打开终端，运行以下命令：

```powershell
# 创建插件项目
dotnet new lmd-plugin -n MyFirstPlugin

# 进入项目目录
cd MyFirstPlugin
```

✅ **成功标志：** 命令执行后没有报错，且生成了 `MyFirstPlugin` 文件夹。

---

## 📝 步骤二：配置插件信息（30秒）

打开 `plugin.json` 文件，修改以下字段：

```json
{
  "id": "com.yourname.myfirstplugin",
  "name": "我的第一个插件",
  "description": "这是一个测试插件",
  "author": "你的名字",
  "version": "1.0.0",
  "apiVersion": "4.0.1",
  "entranceAssembly": "MyFirstPlugin.dll",
  "sharedContracts": []
}
```

⚠️ **重要提示：**
- `id` 必须是唯一的，建议使用反向域名格式（如 `com.yourname.pluginname`）
- `apiVersion` 必须与 SDK 版本匹配
- 保存文件时使用 **UTF-8** 编码

---

## 🔨 步骤三：构建项目（30秒）

在终端中运行：

```powershell
# 构建项目
dotnet build
```

✅ **成功标志：** 看到类似以下的输出：
```
生成成功。
    0 个警告
    0 个错误
```

---

## 📦 步骤四：找到插件包（15秒）

构建完成后，插件包位于：

```
MyFirstPlugin/
└── bin/
    └── Debug/
        └── net10.0/
            └── MyFirstPlugin.laapp    <-- 这就是插件包！
```

⚠️ **什么是 .laapp 文件？**
- `.laapp` 是阑山桌面的插件包格式
- 本质上是一个 ZIP 压缩包，包含插件 DLL 和资源文件
- 不要解压，直接安装即可

---

## 🚀 步骤五：安装到宿主（30秒）

1. **启动阑山桌面**（如果尚未运行）

2. **打开设置**：
   - 右键点击桌面上的阑山桌面图标
   - 选择「设置」

3. **进入插件管理**：
   - 在设置窗口左侧选择「插件」

4. **安装本地插件**：
   - 点击「安装本地插件」按钮
   - 选择刚才生成的 `.laapp` 文件
   - 点击「打开」

5. **重启宿主**：
   - 安装完成后，点击「重启」按钮
   - 阑山桌面将重新启动

---

## ✅ 步骤六：验证安装（15秒）

重启后，再次打开设置 → 插件：

🎉 **成功标志：**
- 在插件列表中看到「我的第一个插件」
- 状态显示为「已启用」
- 作者显示为你设置的名字

![插件列表示意图](此处应有截图位置)

---

## 📂 生成的项目结构

你的项目现在包含以下文件：

```
MyFirstPlugin/
├── plugin.json              # 插件清单文件
├── MyFirstPlugin.csproj     # 项目文件
├── Plugin.cs                # 插件入口类
├── README.md                # 项目说明
└── Localization/            # 本地化文件夹
    ├── zh-CN.json           # 中文资源
    └── en-US.json           # 英文资源
```

---

## 🔍 查看插件代码

打开 `Plugin.cs`，你会看到：

```csharp
using LanMountainDesktop.PluginSdk;
using Microsoft.Extensions.DependencyInjection;
using Microsoft.Extensions.Hosting;

namespace MyFirstPlugin;

[PluginEntrance]
public sealed class Plugin : PluginBase
{
    public override void Initialize(HostBuilderContext context, IServiceCollection services)
    {
        // 插件初始化代码
        // 在这里注册组件、设置页面等
    }
}
```

**关键点：**
- `[PluginEntrance]` 特性标记入口类
- 继承 `PluginBase` 基类
- `Initialize` 方法是插件的初始化入口

---

## 🎉 恭喜！

你已经成功创建并安装了第一个阑山桌面插件！

虽然这个插件目前还没有任何功能，但你已经掌握了：
- ✅ 使用模板创建项目
- ✅ 配置插件信息
- ✅ 构建插件包
- ✅ 安装到宿主

---

## 🚦 常见问题

### 问题 1：构建失败，提示找不到 SDK

**现象：** 错误信息包含 "SDK not found"

**解决：**
1. 确认已安装 .NET 10 SDK：`dotnet --version`
2. 检查 `global.json` 中的版本要求

### 问题 2：宿主提示插件安装失败

**现象：** 安装时弹出错误对话框

**排查步骤：**
1. 检查 `plugin.json` 是否为有效的 JSON 格式
2. 确认 `id` 字段唯一且合法（只能包含字母、数字、点号）
3. 确认 `apiVersion` 与 SDK 版本匹配

### 问题 3：插件列表中不显示

**现象：** 安装后重启，但列表中没有

**排查步骤：**
1. 确认已点击「重启」按钮
2. 检查日志文件：`%LOCALAPPDATA%\LanMountainDesktop\logs\`
3. 确认 `.laapp` 文件完整未损坏

---

## 🎯 下一步

现在你的插件已经能运行了，接下来学习：

👉 **[03-插件项目结构详解](03-插件项目结构详解.md)** - 深入理解每个文件的作用

或者直接进入实战：

👉 **[02-桌面组件系统](../02-核心概念与原理/02-桌面组件系统.md)** - 创建你的第一个桌面组件！

---

## 💡 小贴士

- **快速重建**：修改代码后，只需运行 `dotnet build` 即可重新生成 `.laapp`
- **自动安装**：可以在 IDE 中配置构建后自动复制到宿主插件目录
- **日志调试**：使用 `ILogger` 记录日志，在 `%LOCALAPPDATA%\LanMountainDesktop\logs\` 查看

---

*最后更新：2026年4月*