> ## Documentation Index
> Fetch the complete documentation index at: https://docs.qomicex.top/llms.txt
> Use this file to discover all available pages before exploring further.

# 从零开始开发第一个插件

## 从零开始开发第一个插件

本教程带你从零创建一个最小可运行的 Qomicex 插件。**推荐使用 `qomicex` CLI 脚手架起步**（自动生成合法项目结构），也可手动编写（见下方替代方案）。

## 前置条件

* 已安装 Qomicex 启动器（用于测试）
* [qomicex CLI](https://docs.qomicex.top/plugins/cli.md)（Node.js ≥ 20）：

```bash theme={null}
pnpm --filter @qomicex/cli build
pnpm --filter @qomicex/cli link   # 链接到 PATH，之后可直接用 qomicex
```

首次使用前可跑 `qomicex doctor` 检查 Node / pnpm / 插件项目环境是否就绪（纯只读，不修改任何文件）。

## 一、用 CLI 生成项目（推荐）

```bash theme={null}
qomicex create dev.example.helloworld
cd dev.example.helloworld
pnpm install
qomicex verify     # 立即校验，确认 0 error
```

生成的项目是 Vite + React 19 + TS + Tailwind 工程化结构（详见 [React + Vite 插件开发](https://docs.qomicex.top/plugins/react-plugin.md)），`manifest.json` 已就位：

```json theme={null}
{
  "id": "dev.example.helloworld",
  "name": "Hello World",
  "version": "0.1.0",
  "minLauncherVersion": "0.1.0",
  "layers": ["l2"],
  "permissions": ["config:read", "ui:toast", "network:cors_proxy"],
  "entry": { "frontend": "dist/index.html" }
}
```

关键字段：

* `id`：插件唯一 ID，同时是安装目录名（`plugins/{id}/`），**一经发布不要更改**
* `layers`：图层声明。含脚本页面的插件建议 `["l2", "l3"]`（**默认 iframe 沙箱渲染**；若需内联渲染须在 manifest 显式声明 `"render": "inline"`。激活取决于 `entry.frontend` 是否存在，详见 [layers 图层定义](https://docs.qomicex.top/plugins/manifest.md#layers-图层定义)）
* `permissions`：插件要用的权限（见 [插件 API 完整参考](https://docs.qomicex.top/plugins/plugin-api.md)）
* `entry.frontend`：插件页面入口，`.qplugin` 包内的相对路径

## 二、编写插件页面

创建 `src/App.tsx`（React）或按需修改。以纯 HTML 为例，可在 `index.html` 中直接写：

```html theme={null}
<!DOCTYPE html>
<html>
<head>
  <meta charset="utf-8">
</head>
<body>
  <div class="p-card">
    <div class="p-card-title">Hello, Qomicex!</div>
    <div class="p-card-desc">这是我的第一个插件。</div>
    <button id="btn" class="p-btn p-btn--primary">点我</button>
  </div>

  <script>
    document.getElementById('btn').addEventListener('click', async function () {
      const settings = await window.__PLUGIN_API__.call('getSettings')
      window.__PLUGIN_API__.call('showToast', '设置项数量: ' + Object.keys(settings).length, 'success')
    })
  </script>
</body>
</html>
```

* 样式使用启动器提供的 `.p-*` 组件类（如 `.p-card`、`.p-btn`），自动跟随明暗主题。完整清单见 [UI 组件库](https://docs.qomicex.top/plugins/plugin-ui.md)。
* 插件脚本通过全局对象 `window.__PLUGIN_API__` 与启动器交互。注意：插件激活时脚本即执行（内联或 L2 沙箱），无需进入插件页面，详见 [渲染原理](https://docs.qomicex.top/plugins/pitfalls.md)。
* 工程化插件用 `@qomicex/plugin-ui` React 组件 + Tailwind，见 [React + Vite 插件开发](https://docs.qomicex.top/plugins/react-plugin.md)。

## 三、打包插件

### 用 CLI 打包（推荐）

```bash theme={null}
qomicex pack                # tsc && vite build → release/<id>-<version>.qplugin
qomicex pack --key ./dev-key.pem    # 附签名（离线可验）
```

`.qplugin` 即 zip，`manifest.json` 在根 + `dist/**`。`entry.theme` / `contributes.overlay.file` 若引用 `dist/` 下文件但源码在根目录，`pack` 会自动拷入。

`manifest.json` 必须在压缩包**根目录**，放在子目录里会安装失败。

### 不用 CLI 的手动打包（替代方案）

* 将 `manifest.json` 与资源目录放入一个文件夹
* 用任意 ZIP 工具压缩，确保 `manifest.json` 位于 **ZIP 根目录**
* 将扩展名改为 `.qplugin`

```text theme={null}
my-plugin.qplugin          # 即 zip，manifest.json 在根
```

## 四、安装测试

* 打开 Qomicex 启动器 → 设置 → 插件
* 点击「安装插件」，选择你的 `.qplugin` 文件
* 安装成功后，在插件列表看到卡片，切换开关启用（需重启启动器生效）
* 重启后，侧边栏出现 "Hello" 入口，点击进入插件页面

开发期可用 `qomicex dev` 走调试 harness（无需启动 Tauri/后端，浏览器热重载），详见 [调试与热重载](https://docs.qomicex.top/plugins/debugging.md)。

## 五、常见问题速查

| 现象 | 原因 |
| - | - |
| 安装报 `Invalid plugin package` | `manifest.json` 不在包根目录，或 JSON 解析失败 |
| 插件列表出现但侧边栏没入口 | `contributes.menuItems` 未声明，或未启用插件 |
| 页面空白 / 脚本不执行 | 插件未激活或激活时序问题（见 [避坑指南](https://docs.qomicex.top/plugins/pitfalls.md)） |
| 调用 API 报 `Permission denied` | manifest 的 `permissions` 未包含对应权限 |
| `qomicex pack` 报错 | 先跑 `qomicex verify` / `qomicex lint` 定位问题 |

## 下一步

* 了解 manifest 全部字段：[manifest 清单详解](https://docs.qomicex.top/plugins/manifest.md)
* 了解全部可调用的 API：[插件 API 完整参考](https://docs.qomicex.top/plugins/plugin-api.md)
* 工程化开发：[React + Vite 插件开发](https://docs.qomicex.top/plugins/react-plugin.md)
* 完整 CLI 命令：[CLI 工具参考](https://docs.qomicex.top/plugins/cli.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.