> ## Documentation Index
> Fetch the complete documentation index at: https://supastack.dev/llms.txt
> Use this file to discover all available pages before exploring further.
> For the full documentation corpus in one file, fetch: https://supastack.dev/llms-full.txt

# 如何建構帶 Chrome 擴充套件（MV3）的 SaaS：與主站共享認證和 API

多數團隊為瀏覽器擴充套件另起一套後端。本文演示如何讓 Manifest V3 伴侶擴充套件透過工作區 API 金鑰直連你現有的 SaaS——不重複做認證，不開第二個資料庫。

_釋出於 2026-11-07._
_更新於 2026-11-07._

> **如何建構一個與你的 SaaS 共享後端的 Chrome 擴充套件？**
> 關鍵在於不建第二個後端。MV3 擴充套件無法依賴 HttpOnly Cookie，所以改用工作區 API 金鑰認證：擴充套件帶著綁定單一工作區的受限金鑰呼叫應用版本化 REST API（/api/v1），複用與 Web 應用相同的認證模型、租戶隔離和 Postgres 資料庫。supastack 自帶的 MV3 起手架——彈窗、選項頁、背景 worker、最小權限清單——正是按這套方式接線的。

## 陷阱：不知不覺建了第二個後端

常見劇情是：你的 SaaS 需要一個伴侶擴充套件來採集網頁、剪藏內容或標註頁面。六個月後，你維護著兩套認證系統（Web 用 Cookie，擴充套件用某種手搓方案）、一套擴充套件真正調得動的平行 API，外加一個在兩個本應是同一個的資料儲存之間對齊的同步層。

這些全都沒必要。擴充套件只是你現有產品的一個用戶端——它需要一個拿得住的憑證、一個為程式化存取設計的 API，僅此而已。錯誤在於伸手去建新後端，而不是用一個嚴肅 SaaS 早已具備的工作區 API 金鑰和版本化 REST 端面。


## Manifest V3 實際允許你做什麼

MV3 用短暫存活的 Service Worker 取代了背景頁面，並把擴充套件推向最小權限模型。實務上：不能依賴常駐記憶體狀態；不該去摳 Cookie 做工作階段複用（HttpOnly Cookie 反正也摸不到）；每一項主機權限都是應用商店審核時要回答的問題。

乾淨的答案正是平台已經給你的：一把放在 `chrome.storage.local` 裡的受限憑證，加上指向你應用網域的 HTTPS 呼叫——在安裝後的設定環節以可選主機權限申請，而不是安裝時。


## supastack 的 MV3 起手架：已經接好線的部分

supastack 的 `apps/extension` 是一個刻意保持小巧、零框架的 Manifest V3 伴侶——「儲存頁面到工作區」——端到端演示了整套模式。它透過版本化 REST API `POST /api/v1/content-entries`，把目前分頁的標題、URL 與選取文字存進一條工作區內容記錄。

認證用的是在「設定 → 開發者」下建立的工作區 API 金鑰（`sk_…`）：金鑰只綁定一個工作區，所以綁定本身就是工作區選擇——金鑰永遠寫不到別處。選項頁把應用網址與金鑰存進 `chrome.storage.local`，只為該網域申請存取權，並透過 `GET /api/v1/workspaces/current` 驗證連通。

```
apps/extension/
  manifest.json        MV3: service worker, least-privilege permissions
  src/
    background.js      context-menu save + badge feedback
    popup.html/.js     capture UI — title, URL, selection, note
    options.html/.js   app URL + workspace API key setup
    lib/
      api.mjs          versioned /api/v1 client (key auth)
      capture.mjs      active-tab + selection capture
      config.mjs       chrome.storage.local persistence
```


## 預設最小權限

起手架只帶這件工作真正需要的最小權限集——這對應用商店審核和使用者信任都重要：

- 沒有 `tabs`、沒有 `<all_urls>`、沒有 cookies/webRequest/declarativeNetRequest——起手架誠實地聲明自己不需要什麼。

| 權限 | 用途 |
|---|---|
| activeTab | 僅在調用時讀取目前頁的標題/URL |
| scripting | 讀取被調用分頁內的選取文字 |
| contextMenus | 註冊右鍵「儲存」選單項 |
| storage | 持久化應用網址、API 金鑰與工作區快取 |
| optional_host_permissions | 應用網域在設定時才申請，安裝時零站台存取 |


## 從起手架到你產品的伴侶擴充套件

改品牌就是改 `manifest.json` 的名字；擴充功能才是有意思的部分，而且依然落在同一模式裡——新的採集類型用同一把金鑰呼叫新的 `/api/v1` 端點，由應用 OpenAPI 文件生成的型別化 `@supastack/api-sdk` 保證請求體不走樣。

因為擴充套件與其他用戶端一樣，透過同一套租戶隔離的 API 讀寫，儲存下來的頁面落進 Web 控制台列出的同一批 Postgres 行——一個資料庫、一套認證模型、`workspaceId` 隔離只在同一個地方強制。沒有第二後端，沒有同步，沒有漂移。各檔位見 [定價頁](https://supastack.dev/#pricing)。

|  | 自建第二後端的做法 | supastack MV3 起手架 |
|---|---|---|
| 認證 | 在 Cookie 旁邊手搓一套權杖體系 | 工作區 API 金鑰——與 Web 同一認證模型 |
| API | 為擴充套件新造一套端點 | 版本化 /api/v1 + OpenAPI 型別化 SDK |
| 資料 | 第二儲存 + 同步邏輯 | 同一批 Postgres 行，工作區隔離 |
| 權限 | 圖省事申請寬泛存取 | 最小權限清單，對審核友好 |


## 常見問題：SaaS + Chrome 擴充套件共用一套後端

開發者在交付擴充套件伴侶之前常問的問題：

- 為什麼用 API 金鑰而不是使用者的工作階段 Cookie?, HttpOnly Cookie 在設計上就對擴充套件 JS 不可見，而 MV3 Service Worker 生命短暫——`chrome.storage.local` 裡一把受限的 `sk_…` 金鑰持久、可撤銷，且綁定單一工作區，永遠跨不了租戶。
- 擴充套件在 Firefox 上能用嗎?, MV3 支援同一套端面；程式碼使用 `browser ?? chrome` 命名空間墊片且以 Chromium 優先開發，所以 Firefox 是移植而非重寫。
- 開箱就能上商店嗎?, 它是一個生產級模式的起手架，不是商店提交件——你需要給清單改名、加自己的採集邏輯、寫商店文案。最難的部分（認證、API、租戶隔離）已經做完。
- 哪個檔位包含擴充套件?, $299 的 Full Bundle 在同一倉庫交付全部五個端面——兩個 Web 引擎、Expo、Tauri 與擴充套件起手架。