workers-best-practices

你對 Cloudflare Workers API、型別和設定的知識可能已過時。對於任何 Workers 程式碼任務（撰寫或審查），請優先檢索而非預先訓練。

檢索來源

在撰寫或審查 Workers 程式碼之前，請取得最新版本。不要依賴內建知識來處理 API 簽名、設定欄位或綁定型別。

來源	如何檢索	用途
Workers 最佳實踐	取得 https://developers.cloudflare.com/workers/best-practices/workers-best-practices/	規範性規則、模式、反模式
Workers 型別	請參閱 references/review.md 了解檢索步驟	API 簽名、處理器型別、綁定型別
Wrangler 設定結構	node_modules/wrangler/config-schema.json	設定欄位、綁定形狀、允許值
Cloudflare 文件	搜尋工具或 https://developers.cloudflare.com/workers/	API 參考、相容性日期/標誌

第一步：取得最新參考資料

在審查或撰寫 Workers 程式碼之前，請檢索目前的最佳實踐頁面和相關型別定義。如果專案的 node_modules 中有較舊版本，請優先使用最新發布的版本。

# 取得最新的 workers 型別
mkdir -p /tmp/workers-types-latest && \
  npm pack @cloudflare/workers-types --pack-destination /tmp/workers-types-latest && \
  tar -xzf /tmp/workers-types-latest/cloudflare-workers-types-*.tgz -C /tmp/workers-types-latest
# 型別位於 /tmp/workers-types-latest/package/index.d.ts

參考文件

• references/rules.md — 所有最佳實踐規則，附有程式碼範例和反模式
• references/review.md — 型別驗證、設定驗證、綁定存取模式、審查流程

規則快速參考

設定

規則	摘要
相容性日期	新專案將 compatibility_date 設為今天；現有專案定期更新
nodejs_compat	啟用 nodejs_compat 標誌 — 許多函式庫依賴 Node.js 內建模組
wrangler types	執行 wrangler types 產生 Env — 絕不手寫綁定介面
機密	使用 wrangler secret put，絕不將機密硬編碼在設定或原始碼中
wrangler.jsonc	使用 JSONC 設定非機密設定 — 較新功能僅支援 JSON

請求和回應處理

規則	摘要
串流	串流處理大型/未知負載 — 絕不對無界資料使用 await response.text()
waitUntil	使用 ctx.waitUntil() 處理回應後工作；不要解構 ctx

架構

規則	摘要
綁定優於 REST	使用程序內綁定（KV、R2、D1、Queues）— 而非 Cloudflare REST API
Queues 與 Workflows	將非同步/背景工作移出關鍵路徑
服務綁定	使用服務綁定進行 Worker 間呼叫 — 而非公開 HTTP
Hyperdrive	對於外部 PostgreSQL/MySQL 連線，一律使用 Hyperdrive

可觀測性

規則	摘要
日誌與追蹤	在設定中啟用 observability 並設定 head_sampling_rate；使用結構化 JSON 日誌

程式碼模式

規則	摘要
無全域請求狀態	絕不將請求範圍的資料儲存在模組層級變數中
浮動 Promise	每個 Promise 必須被 await、return、void，或傳遞給 ctx.waitUntil()

安全性

規則	摘要
Web Crypto	使用 crypto.randomUUID() / crypto.getRandomValues() — 絕不使用 Math.random() 處理安全性
不使用 passThroughOnException	使用明確的 try/catch 搭配結構化錯誤回應

需要標記的反模式

反模式	為什麼重要
對無界資料使用 await response.text()	記憶體耗盡 — 128 MB 限制
在原始碼或設定中硬編碼機密	透過版本控制洩漏憑證
使用 Math.random() 產生令牌/ID	可預測，非加密安全
裸 fetch() 沒有 await 或 waitUntil	浮動 Promise — 結果遺失，錯誤被吞沒
模組層級可變變數儲存請求狀態	跨請求資料洩漏、過時狀態、I/O 錯誤
從 Worker 內部呼叫 Cloudflare REST API	不必要的網路跳躍、驗證開銷、增加延遲
使用 ctx.passThroughOnException() 作為錯誤處理	隱藏錯誤，使除錯變得不可能
手寫 Env 介面	與實際 wrangler 設定綁定脫節
直接字串比較機密值	計時側通道 — 使用 crypto.subtle.timingSafeEqual
解構 ctx（const { waitUntil } = ctx）	失去 this 綁定 — 執行時拋出「Illegal invocation」
在 Env 或處理器參數上使用 any	破壞所有綁定存取的型別安全
雙重轉型 as unknown as T	隱藏真實型別不相容 — 修正設計
在平台基底類別上使用 implements（而非 extends）	舊寫法 — 失去 this.ctx、this.env。適用於 DurableObject、WorkerEntrypoint、Workflow
在平台基底類別內部使用 env.X	在繼承 DurableObject、WorkerEntrypoint 等的類別中應使用 this.env.X

審查流程

1. 檢索 — 取得最新的最佳實踐頁面、workers 型別和 wrangler 結構
2. 讀取完整檔案 — 不僅是差異；綁定存取模式的上下文很重要
3. 檢查型別 — 綁定存取、處理器簽名、無 any、無不安全轉型（請參閱 references/review.md）
4. 檢查設定 — compatibility_date、nodejs_compat、observability、機密、綁定與程式碼一致性
5. 檢查模式 — 串流、浮動 Promise、全域狀態、序列化邊界
6. 檢查安全性 — crypto 使用、機密處理、計時安全比較、錯誤處理
7. 使用工具驗證 — npx tsc --noEmit、lint 檢查 no-floating-promises
8. 參考規則 — 請參閱 references/rules.md 了解每個規則的正確模式

範圍

此技能涵蓋 Workers 特定的最佳實踐和程式碼審查。相關主題：

• Durable Objects：載入 durable-objects 技能
• Workflows：請參閱 Workflows 規則
• Wrangler CLI 指令：載入 wrangler 技能

原則

• 要確定。 在標記之前先檢索。如果不確定某個 API、設定欄位或模式，請先查閱文件。
• 提供證據。 引用行號、工具輸出或文件連結。
• 專注於開發者會複製的內容。 範例和文件中的 Workers 程式碼會被貼到生產環境。
• 正確性重於完整性。 一個能運作的簡潔範例勝過一個有錯誤的全面範例。