Supabase Edge Functions production guide：邊界、部署與可觀測性

Edge Function 很適合處理需要 secret、第三方 API 或受控權限的短時間 request，但它不是把所有 backend code 搬到一個 index.ts 的理由。production-safe 設計必須先定義 function contract、身份模型、資料一致性與失敗方式，再選擇 runtime。對長時間工作、重型 batch 或需要持久 connection 的流程，queue/worker 可能比 request-bound function 更合適。 截至 2026-07-29，Supabase 官方描述 Edge Function request 會先進入 gateway，再由 Edge Runtime 執行 Deno-compatible TypeScript；官方同時提醒 cold start 可能存在，function 應短小且冪等，secret 透過 project secrets/environment 取得。本地開發使用 Supabase CLI 的 Edge Runtime，以縮小 local/production 差異。 實作步驟 第一步寫 contract。記錄 method、path、authentication、input schema、最大 payload、success/error response、timeout、side effects 與 idempotency key。區分三類 endpoint：user-authenticated、server-to-server、public-but-signed webhook。不要用同一 verify_jwt=false function 同時處理公開與會員操作。 目錄按 function 隔離，shared code 放 _shared ，test 另置。依官方 development guide，Supabase CLI 可啟動 local stack 與特定 function。對外 response 應有穩定 error code，不直接洩漏 stack 或 provider response。 supabase/ config.toml functions/ _shared/ cors.ts errors.ts create-report/ index.ts create-report-test/ index.test.ts 第二步設定身份。一般 user function 保留預設 JWT verification，從 Authorization 取得 caller，資料存取仍走 RLS。只有像 Stripe webhook 這種沒有 Supabase user JWT、但有自己的簽章驗證機制的 endpoint 才在 config.toml 精確關閉： [functions.create-report] verify_jwt = true [functions.signed-webhook] verify_jwt = false 關閉 gateway JWT 後不是「不需驗證」；handler 必須先驗外部簽章、timestamp/replay window 或 server key，再執行任何 side effect。CORS 也不是 authentication。只允許實際前端 origins，依 request Origin 回精確值並加 Vary: Origin ；credentialed response 不可使用 * 。 第三步管理 secrets。production secret 用 Supabase Dashboard/CLI 的 secrets 機制，不 commit .env 。本地使用獨立 .env.local 並列入 ignore，採測試 credential。function 只讀需要的變數，啟動時檢查缺少值並 fail closed。log 可記錄 secret 名稱缺失，但不可記錄值。 第四步把 database write 變成一致操作。user-scoped 查詢使用 caller token client 讓 RLS 生效；管理操作才使用 server secret。跨多表狀態轉移應交給 transaction/RPC，而不是依序呼叫三次 REST。外部 API timeout 必須有 idempotency key 或 outbox，避免 client retry 產生兩筆資源。 第五步建立 typed validation。即使 TypeScript 已定義 interface，HTTP JSON 在 runtime 仍是不可信資料。驗證 content type、JSON shape、字串長度、enum、URL/ID 格式與 nested array 上限。對無效輸入回 400，無身份回 401，身份存在但無權限回 403，衝突回 409；不要把所有 exception 都變成 200。 第六步加入可觀測性。為每個 request 產生/傳遞 request ID，記錄 function 版本、duration bucket、status、provider request ID 與不含個資的 error class。不要記錄 Authorization、Cookie、API key、完整付款資料或使用者 prompt。對 5xx、latency 與重試率設 alert，但門檻需由實際 baseline 決定。 第七步建立 release gate。pin dependency/version，執行 format、lint、unit、local integration 與負面安全測試，再 deploy 指定 function，不要無意部署所有實驗 function。保存 deploy commit SHA、config 與 secret names（不是 values）。先打健康/無副作用 request，再跑真實 read-only canary。 失敗與復原 local 可用、remote 失敗時，先比對 Deno/import lock、環境變數名稱、config entrypoint、JWT gate 與 region/network restriction。使用 --debug 只輸出必要資訊，先清除 log 中可能的 credentials 再分享。 401 表示 gateway 或 handler authentication 不通過；403 表示 caller 通常已識別但被權限拒絕。不要為了修 401 全域加 --no-verify-jwt 。只在 contract 本來就是 signed webhook 時關閉該 function 的 JWT，並證明替代簽章驗證存在。 若外部 API timeout，先判斷 operation 是否可能已成功。沒有 idempotency 保護時不可盲目重送 mutation；查 provider state 或讓人工 reconciliation。若 function 已寫 DB 再失敗，使用明確狀態 pending/failed 與 retry worker，不要把半完成 row 刪掉掩蓋。 deploy 造成 5xx 時，用保存的前一 commit/config 重新 deploy 指定 function，或以 feature flag 停止流量。secret rotation 與 code rollback 分開處理：若是 key 洩漏，回滾 code 不會讓舊 key失效，仍需 provider/Supabase 端輪替。 驗證指令 在 local 啟動 stack 與單一 function，再用 curl 測 method、CORS、Auth 和 invalid payload： supabase start supabase functions serve create-report --env-file .env.local curl -i -X OPTIONS http://127.0.0.1:54321/functions/v1/create-report \ -H 'Origin: https://allowed.example' curl -i -X POST http://127.0.0.1:54321/functions/v1/create-report \ -H 'Content-Type: application/json' -d '{}' 驗收矩陣包含：無 token/過期 token/另一使用者、錯誤 origin、錯誤 method、invalid/oversized JSON、相同 idempotency key 重送、兩個並行 request、provider timeout、DB 拒絕與 secret 缺少。確認 response code、資料最終狀態與 log redaction，再 deploy 並用 remote read-only canary 驗證。 官方來源 Supabase Edge Functions Supabase Development Environment Supabase Function Configuration Supabase Environment Variables / Secrets 延伸閱讀 從 技術文章 查看 Auth、Stripe Checkout 與資料遷移。 在 課程總覽 建立可測試的 Edge Function 專案。 若 remote failure 無法重現，可由 聯絡頁 提供 redacted request ID。