---
url: https://docs.ogmabox.com/zh-Hant/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-Hant/plugins/backend-sdk)
* [前端 SDK](/zh-Hant/plugins/frontend-sdk)