EmDash 外掛程式以兩種格式之一交付：沙盒式或原生。這個選擇會影響外掛程式的安裝方式、執行時期獲得的強制執行以及可用的功能。
預設使用沙盒式。 沙盒式外掛程式可以發布到市集並從管理介面一鍵安裝。原生外掛程式需要修改程式碼、執行 npm install 並在每個想要使用它們的網站上重新部署。沙盒式是終端使用者想要的。
僅在需要沙盒無法提供的功能時才選擇原生。
概覽
| 沙盒式 | 原生 | |
|---|---|---|
描述符上的 format 欄位 | "standard" | "native" |
| 安裝方法 | 從管理市集一鍵安裝 | npm install + 編輯 astro.config |
| 執行環境 | 由沙盒執行器提供的隔離執行時期 | 與您的 Astro 網站相同的處理程序 |
| 功能 | 由沙盒橋接強制執行 | 由相同橋接在處理程序內強制執行 |
| 資源限制 | 由執行器強制執行 — 通常是 CPU、子請求、執行時間、記憶體 | 無 |
| 網路存取 | 僅 ctx.http，限制為 allowedHosts | 僅 ctx.http，限制為 allowedHosts |
直接 fetch() / process.env | 被執行器阻止 | 可能（外掛程式碼共用執行時期） |
| 分發方式 | 市集上的 .tar.gz 套件 | npm 套件 |
| 管理介面 | Block Kit（JSON 描述）路由 | React 元件或 Block Kit |
| 設定介面 | Block Kit 頁面 + KV 讀取 | admin.settingsSchema（自動表單）或 Block Kit |
| Portable Text 轉譯元件 | 不可用 | componentsEntry 提供 Astro 元件 |
| 頁面中繼資料貢獻 | page:metadata 掛鉤 — meta/property 標籤、白名單 <link> rels、JSON-LD | page:metadata 掛鉤（相同介面） |
| 頁面片段注入 | 不可用 — 僅透過 page:metadata 注入 meta/JSON-LD | page:fragments 掛鉤 — 內嵌指令碼、外部指令碼、原始 HTML |
| 建構函式選項 | 無 — 在執行時期從 KV 讀取設定 | 描述符上的 options |
選擇原生會失去什麼
原生外掛程式看起來像同一事物的更強大版本，確實如此 — 但代價很高：
- 沒有市集。 每個網站都必須安裝您的 npm 套件、編輯
astro.config.mjs並重新部署。 - 沒有隔離。 外掛程式中的錯誤可能會導致主機處理程序當機或耗盡其 CPU 預算。掛鉤中未處理的拒絕可能會連同周圍的請求一起倒下。
- 使用者的信任負擔。 原生外掛程式具有與主機網站相同的存取權限。終端使用者無法僅透過功能宣告來稽核它們。
如果您的外掛程式可以在沙盒中完成工作，就應該這樣做。
何時選擇原生
選擇原生有三個原因，它們都與需要與主機網站進行建置時期整合的功能有關：
-
自訂 React 管理頁面或小工具。 沙盒式外掛程式使用 Block Kit 描述其管理介面 — 這是管理員代表外掛程式轉譯的 JSON 結構描述。如果您需要完整的 React（自訂掛鉤、第三方元件、複雜狀態），則需要原生。
-
用於在公開網站上轉譯 Portable Text 區塊的 Astro 元件。 外掛程式可以使用
format: "standard"宣告自訂區塊類型，但在公開網站上轉譯它的 Astro 元件必須在建置時期從 npm 載入。只有原生外掛程式可以提供componentsEntry。 -
將原始 HTML、指令碼或樣式表注入公開頁面。
page:fragments掛鉤將第一方程式碼傳送到訪客的瀏覽器 — 在任何沙盒邊界之外。它僅限於原生外掛程式。沙盒式外掛程式仍然可以透過page:metadata掛鉤為公開頁面做出貢獻，它涵蓋了許多實際使用案例：meta標籤（name+content）— SEO 描述、robots 指令、Twitter Cardsproperty標籤 — OpenGraph 和其他基於屬性的中繼資料- 具有安全鎖定 rel 白名單的
link標籤（canonical、alternate、author、license、nlweb、site.standard.document）—stylesheet、prefetch和類似的資源載入 rels 被刻意不允許 - JSON-LD 圖
如果您的「頁面注入」需求是結構化資料或 SEO 中繼資料，請保持沙盒式並使用
page:metadata。如果您確實需要將 JavaScript 或 HTML 傳送到訪客的瀏覽器，那就是選擇原生的情況。
如果您不確定，請選擇沙盒式。您始終可以稍後遷移到原生 — 但相反則更困難，因為原生專有功能沒有沙盒等效物。
沙盒執行器和平台支援
沙盒本身是可插拔的。EmDash 公開了一個 sandboxRunner 組態選項，執行器決定如何隔離外掛程式碼 — 外掛程式格式本身沒有任何 Cloudflare 特定的內容。
今天大多數網站使用的執行器是來自 @emdash-cms/cloudflare 的 sandbox()，它使用 Cloudflare Workers 的 Dynamic Worker Loader。Worker Loader 按外掛程式 ID 快取 V8 隔離，因此隔離冷啟動成本只需支付一次；執行器在每次呼叫時建構一個新的 worker 存根和橋接繫結，因為存根和繫結與呼叫請求的 I/O 情境繫結。其他平台（透過 workerd 的 Node.js 以及可能的 Deno）的執行器正在開發中。
如果未組態執行器，或者如果組態的執行器報告在目前平台上不可用，則在啟動時跳過 sandboxed: [] 下列出的外掛程式，並記錄偵錯層級日誌。
如果您希望標準格式外掛程式在沒有沙盒執行器的平台上執行，請將其從 sandboxed: [] 移動到 plugins: [] 陣列 — 它將在處理程序中執行。功能宣告仍然受到尊重（相同的 PluginContext 工廠限制 ctx.content、ctx.http 等），但沒有隔離邊界，沒有資源限制，有錯誤或惡意的外掛程式可以直接呼叫 fetch()、讀取環境變數或阻止事件迴圈。如果沒有活動的沙盒執行器，出於信任目的，請將每個外掛程式視為原生外掛程式。