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

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

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

---

🎯 目标

完成本指南后，你将：

• ✅ 创建一个可运行的插件项目
• ✅ 在宿主中成功加载插件
• ✅ 在插件列表中看到你的插件

---

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

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

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

# 进入项目目录
cd MyFirstPlugin

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

---

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

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

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

⚠️ 重要提示：

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

---

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

在终端中运行：

# 构建项目
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，你会看到：

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-插件项目结构详解 - 深入理解每个文件的作用

或者直接进入实战：

👉 02-桌面组件系统 - 创建你的第一个桌面组件！

---

💡 小贴士

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

---

最后更新：2026年4月