---
url: https://docs.ogmabox.com/zh/plugins/quickstart.md
description: 通过最小后端示例和可选的前端面板，在几分钟内创建并安装你的第一个 Ogma 插件。
---

# 插件快速入门 {#plugin-quickstart}

本指南帮助你从空文件夹快速搭建可运行的插件。

## 1) 创建最小纯后端插件 {#\_1-create-a-minimal-backend-only-plugin}

创建一个包含以下文件的文件夹：

```text
my-plugin/
  manifest.json
  backend/
    script.js
```

`manifest.json`:

```json
{
  "id": "my-plugin",
  "name": "My Plugin",
  "version": "0.1.0",
  "plugins": [
    {
      "kind": "backend",
      "id": "my-plugin-backend",
      "entrypoint": "backend/script.js"
    }
  ]
}
```

`backend/script.js`:

```js
async function init(sdk) {
  sdk.console.log("Plugin started");

  sdk.events.onInterceptResponse(function(req, res) {
    if (!res) return;
    if (res.getCode() === 403) {
      sdk.console.warn("403 on " + req.getUrl());
    }
  });
}
```

通过**插件 > 安装**选择该文件夹，启用插件，并确认日志中显示 `Plugin started`。

## 2) 如果使用 TypeScript {#\_2-if-you-are-using-typescript}

使用以下结构：

```text
my-plugin/
  manifest.json
  backend/
    src/index.ts
```

使用以下命令打包：

```bash
pnpm add -D @ogmabox/ogma-sdk esbuild typescript
pnpm exec esbuild backend/src/index.ts \
  --bundle \
  --platform=neutral \
  --format=iife \
  --external:@ogma/sdk --external:@ogmabox/ogma-sdk \
  --outfile=backend/script.js
```

然后按上述步骤安装该文件夹。

## 3) 稍后添加前端 {#\_3-add-a-frontend-later}

仅在需要面板时添加前端条目和 UI 文件：

```text
my-plugin/
  frontend/
    script.js
    style.css   # optional
```

然后在 `manifest.json` 中添加以下内容：

```json
{
  "kind": "frontend",
  "id": "my-plugin-frontend",
  "entrypoint": "frontend/script.js",
  "backend": { "id": "my-plugin-backend" }
}
```

前端通信请使用 `window.ogmaSDK.ready(...)`，并将后端调用保留在 `sdk.api` 处理函数中。

## 4) 通常需要的权限 {#\_4-permissions-you-almost-always-need}

对于上述后端示例：

* 无需额外权限（安全的默认权限会自动授予）

如果插件发送出站请求，请添加：

```json
"permissions": ["send_requests"]
```

如果插件写入安全发现，请添加：

```json
"permissions": ["write_findings"]
```

仅申请实际使用的权限。

## 第一个插件的故障排查 {#troubleshooting-first-plugin}

* `Plugin failed to initialize` → 打开**日志**，确认已定义 `init(sdk)`。
* `Invalid manifest` → 检查 JSON 中的逗号和引号。
* 回调未触发 → 确认插件已启用，且已注册相应事件（`onInterceptResponse`）。

完整 API 参考：

* [插件系统](./README)
* [后端 SDK](/zh/plugins/backend-sdk)
* [前端 SDK](/zh/plugins/frontend-sdk)