適合:用 Cloudflare Workers 寫網站或 API 的開發者、負責部署與維運的人
Cloudflare Workers 開發與排錯
本機明明好好的,一部署到 Workers 就出錯?這裡照著上線的順序整理:先把帳號和密鑰設好,再確認建置、預覽網址和存取權限,最後學會看錯誤訊息和 traces,找出問題卡在哪裡。
開工前,帳號和密鑰設好了嗎?
確認 Wrangler 登入的是哪個帳號、密鑰從哪裡讀進來,本機才能跑得跟線上一樣。
- 1. 分開管理不同部署帳號
Wrangler auth profiles:多個 Cloudflare 帳號怎麼避免部署錯環境
Wrangler auth profiles 可把 OAuth 登入綁到專案資料夾,自動選擇 Cloudflare 帳號。本文整理建立方式、account_id 防呆,以及 CI API token 的優先順序。
- 2. 只授權需要的 OAuth scopes
Cloudflare Wrangler OAuth 權限怎麼選?optional scopes 與重新授權排錯
Cloudflare Wrangler 與 API MCP server 現在可在 OAuth 授權時取消不需要的 optional scopes。本文整理 wrangler login、scope 清單、最小權限、缺少權限時重新授權與 CI API token 的分工。
- 3. 設定本機 secrets
Cloudflare Workers 本機秘密怎麼放:.dev.vars、.env 與 secrets.required 的選擇
Cloudflare Workers 本機開發的秘密值該放在哪裡?本文整理 .dev.vars、.env 與 secrets.required 的載入邊界,說明環境檔優先順序與部署 secret 分工,避免 API 金鑰進入 Wrangler 設定檔。
- 4. 批次更新與刪除 Secrets
Wrangler secret bulk 怎麼用?批次更新、刪除 Cloudflare Workers Secrets
Wrangler secret bulk 可用一個 JSON 或 .env 檔批次管理 Cloudflare Workers Secrets。本文整理新增、更新、刪除與保留未列出項目的差異,並比較部署時的 --secrets-file、檔案保護與 CI 驗證流程。
- 5. 檢查 bindings、logs 與 traces
Cloudflare Workers Local Explorer 怎麼用?用 wrangler dev 看 bindings、logs 與 traces
Cloudflare Workers Local Explorer 可在 wrangler dev 中檢查 KV、R2、D1、Durable Objects、Workflow、logs 與 traces。本文整理版本需求、啟動方式、API 與安全的除錯流程。
- 6. 排查本機 dev 的連線中斷
Wrangler dev 出現 Network connection lost 怎麼查?版本 bisect 與 Miniflare v5
Wrangler dev 出現 Network connection lost 時,先分辨 Worker request 與本機 dev server,再用版本 bisect、Miniflare v5 變更與最小 WebSocket 重現條件定位問題,避免把上游回歸誤判成程式錯誤。
建置失敗,或升級後怪怪的?
上傳前先處理建置錯誤、啟動太慢和相容性設定,省得到了線上才發現。
- 7. 排查 Tailwind 3 建置 EMFILE
Cloudflare Workers 建置 EMFILE:Tailwind 3 的暫時處理方式
Cloudflare Workers Builds 在 Astro 靜態建置時出現 EMFILE,錯誤指向 tailwind.config.cjs。本文記錄 Tailwind 3 平行讀檔的排查、正式建置改用 raw content 的暫時處理,以及 CSS 比對、限制模擬與雲端部署的驗證結果。
- 8. 找出拖慢啟動的 bundle 與初始化
Cloudflare Workers 啟動太慢怎麼查?用 Wrangler check startup 找出 bundle 與全域初始化
Cloudflare Workers 出現 startup 超時或 bundle 變大時,先用 Wrangler check startup 讀取 CPU profile,再用 deploy dry-run 查看目前唯一計算的 64 MiB 未壓縮 bundle 大小,分清啟動初始化與部署容量問題。
- 9. 驗證相容性日期與 flags
Cloudflare Workers compatibility_date 怎麼升:先盤點 flags,再更新日期
Cloudflare Workers 的 compatibility_date 決定採用哪些相容性變更。本文補上 2026-08-04 後 Node.js 相容性預設行為,並整理 flags、測試、rollback 與分階段部署。
- 10. 測試 production build 的請求行為
Cloudflare Workers integration test 怎麼寫?用 createTestHarness 測 production build
Cloudflare Workers 新增 createTestHarness,可在 Node.js test runner 中測試一個或多個 Worker 的 production build、route 與外部 fetch。本文整理 Vitest 最小範例與 unit test 的分工。
網址、權限和資料都對嗎?
逐一確認預覽網址、存取保護、轉址順序,還有 KV 這類資料有沒有正確寫入。
- 11. 盤點預覽與 workers.dev 入口
Cloudflare Workers Preview URL 怎麼關?用 workers_dev 與 preview_urls 避免誤公開
Cloudflare Workers 的 Preview URL 可能和 workers.dev 使用不同預設。本文整理 Wrangler 版本差異、preview_urls 設定、Dashboard 開關與 Cloudflare Access,協助你在測試、部署與關閉公開入口時先確認實際暴露範圍。
- 12. 設定 Worker 的 Access 保護
Cloudflare Workers 怎麼套 Access?用 Worker scope 保護所有入口
Cloudflare Access 現在能直接套用到單一 Worker 或全部 Workers。本文整理 preview、production、workers.dev 與自訂網域的保護範圍,並用 wrangler dev 驗證登入身分。
- 13. 安排靜態與動態轉址
Cloudflare Workers 的 _redirects:先排靜態規則,再處理動態路徑
Cloudflare Workers Static Assets 的 _redirects 會受規則順序與靜態、動態數量上限影響。本文整理排序、測試與擴充策略,避免重新導向在部署後才失效,並附上上線驗證方法。
- 14. 檢查部署送出的依賴資料
Cloudflare Workers 上傳 npm 依賴資料:部署前先決定要不要關閉
Cloudflare Workers 的 Wrangler 會在部署或上傳版本時傳送 npm 套件名稱與版本中繼資料。本文用可執行的盤點流程,確認受影響的 Worker、CI 部署入口、帳號存取與資料揭露範圍,再決定是否關閉這個預設啟用的設定。
- 15. 遷移舊的 KV REST API 路徑
Cloudflare Workers KV API 路徑即將淘汰:如何從 workers/namespaces 遷移
Cloudflare Workers KV 已淘汰舊的 workers/namespaces REST API 路徑,並預計 2026 年 10 月 15 日停止支援。本文整理 endpoint 對照、程式碼盤點、驗證請求與遷移陷阱。
- 16. 確認 KV 批次寫入的二進位資料
wrangler kv bulk put 二進位資料損壞?先升級 4.125.0
Wrangler 4.125.0 修正 `kv bulk put` 將含有無效 UTF-8 位元組的 base64 值寫壞到本機 KV 的問題。本文說明受影響範圍、Wrangler v4 的 local/remote 邊界、可重現的驗證流程,以及升級後如何避免把測試資料誤寫到正式 KV。
線上出錯,從哪裡查起?
依錯誤類型選對方法:看請求內容、查 CPU 和記憶體限制,或用 traces 追跨服務的呼叫。
- 17. 找出重複讀取的 request body
Cloudflare Workers request body 已被讀取怎麼修?先找第一個 reader 再 clone
Cloudflare Workers 出現 request body already used 或 TypeError 時,先找出哪個 middleware 讀了 json、formData 或 text,再選擇單次解析、事前 clone 或串流轉送,避免重複讀取和不必要的記憶體負擔。
- 18. 分辨 CPU 與記憶體問題
Cloudflare Workers Error 1102 怎麼查?先分 CPU 與記憶體
Cloudflare Workers 遇到 Error 1102 時,先用 Workers Logs 分辨 CPU time 與 isolate 記憶體,再用輸入邊界、CPU profile 和串流處理定位問題,避免只改方案或盲目重寫 fetch。
- 19. 補上應用程式操作的 span
Cloudflare Workers 自訂 span 怎麼用?比較 enterSpan 與 startSpan
Cloudflare Workers 自訂 span 怎麼加?本文比較 enterSpan、startActiveSpan 與 startSpan 的生命週期,示範加入屬性和例外事件,並整理抽樣、錯誤處理與 trace ID 限制,適合補上應用程式內部操作的追蹤。
- 20. 追查跨 Worker 與 Durable Objects 延遲
Workers RPC 追蹤怎麼看?用 traces 找跨 Worker 與 Durable Objects 延遲
Cloudflare Workers traces 可把跨 Worker 與 Durable Objects 的 JavaScript RPC session、invocation、method call 放進同一條追蹤。本文整理 traces 設定、dashboard 閱讀順序、jsrpc 屬性與沒有資料時的排查。