Stage 01

開工前,帳號和密鑰設好了嗎?

確認 Wrangler 登入的是哪個帳號、密鑰從哪裡讀進來,本機才能跑得跟線上一樣。

  1. 1. 分開管理不同部署帳號

    Wrangler auth profiles:多個 Cloudflare 帳號怎麼避免部署錯環境

    Wrangler auth profiles 可把 OAuth 登入綁到專案資料夾,自動選擇 Cloudflare 帳號。本文整理建立方式、account_id 防呆,以及 CI API token 的優先順序。

  2. 2. 只授權需要的 OAuth scopes

    Cloudflare Wrangler OAuth 權限怎麼選?optional scopes 與重新授權排錯

    Cloudflare Wrangler 與 API MCP server 現在可在 OAuth 授權時取消不需要的 optional scopes。本文整理 wrangler login、scope 清單、最小權限、缺少權限時重新授權與 CI API token 的分工。

  3. 3. 設定本機 secrets

    Cloudflare Workers 本機秘密怎麼放:.dev.vars、.env 與 secrets.required 的選擇

    Cloudflare Workers 本機開發的秘密值該放在哪裡?本文整理 .dev.vars、.env 與 secrets.required 的載入邊界,說明環境檔優先順序與部署 secret 分工,避免 API 金鑰進入 Wrangler 設定檔。

  4. 4. 批次更新與刪除 Secrets

    Wrangler secret bulk 怎麼用?批次更新、刪除 Cloudflare Workers Secrets

    Wrangler secret bulk 可用一個 JSON 或 .env 檔批次管理 Cloudflare Workers Secrets。本文整理新增、更新、刪除與保留未列出項目的差異,並比較部署時的 --secrets-file、檔案保護與 CI 驗證流程。

  5. 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. 6. 排查本機 dev 的連線中斷

    Wrangler dev 出現 Network connection lost 怎麼查?版本 bisect 與 Miniflare v5

    Wrangler dev 出現 Network connection lost 時,先分辨 Worker request 與本機 dev server,再用版本 bisect、Miniflare v5 變更與最小 WebSocket 重現條件定位問題,避免把上游回歸誤判成程式錯誤。

Stage 02

建置失敗,或升級後怪怪的?

上傳前先處理建置錯誤、啟動太慢和相容性設定,省得到了線上才發現。

  1. 7. 排查 Tailwind 3 建置 EMFILE

    Cloudflare Workers 建置 EMFILE:Tailwind 3 的暫時處理方式

    Cloudflare Workers Builds 在 Astro 靜態建置時出現 EMFILE,錯誤指向 tailwind.config.cjs。本文記錄 Tailwind 3 平行讀檔的排查、正式建置改用 raw content 的暫時處理,以及 CSS 比對、限制模擬與雲端部署的驗證結果。

  2. 8. 找出拖慢啟動的 bundle 與初始化

    Cloudflare Workers 啟動太慢怎麼查?用 Wrangler check startup 找出 bundle 與全域初始化

    Cloudflare Workers 出現 startup 超時或 bundle 變大時,先用 Wrangler check startup 讀取 CPU profile,再用 deploy dry-run 查看目前唯一計算的 64 MiB 未壓縮 bundle 大小,分清啟動初始化與部署容量問題。

  3. 9. 驗證相容性日期與 flags

    Cloudflare Workers compatibility_date 怎麼升:先盤點 flags,再更新日期

    Cloudflare Workers 的 compatibility_date 決定採用哪些相容性變更。本文補上 2026-08-04 後 Node.js 相容性預設行為,並整理 flags、測試、rollback 與分階段部署。

  4. 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 的分工。

Stage 03

網址、權限和資料都對嗎?

逐一確認預覽網址、存取保護、轉址順序,還有 KV 這類資料有沒有正確寫入。

  1. 11. 盤點預覽與 workers.dev 入口

    Cloudflare Workers Preview URL 怎麼關?用 workers_dev 與 preview_urls 避免誤公開

    Cloudflare Workers 的 Preview URL 可能和 workers.dev 使用不同預設。本文整理 Wrangler 版本差異、preview_urls 設定、Dashboard 開關與 Cloudflare Access,協助你在測試、部署與關閉公開入口時先確認實際暴露範圍。

  2. 12. 設定 Worker 的 Access 保護

    Cloudflare Workers 怎麼套 Access?用 Worker scope 保護所有入口

    Cloudflare Access 現在能直接套用到單一 Worker 或全部 Workers。本文整理 preview、production、workers.dev 與自訂網域的保護範圍,並用 wrangler dev 驗證登入身分。

  3. 13. 安排靜態與動態轉址

    Cloudflare Workers 的 _redirects:先排靜態規則,再處理動態路徑

    Cloudflare Workers Static Assets 的 _redirects 會受規則順序與靜態、動態數量上限影響。本文整理排序、測試與擴充策略,避免重新導向在部署後才失效,並附上上線驗證方法。

  4. 14. 檢查部署送出的依賴資料

    Cloudflare Workers 上傳 npm 依賴資料:部署前先決定要不要關閉

    Cloudflare Workers 的 Wrangler 會在部署或上傳版本時傳送 npm 套件名稱與版本中繼資料。本文用可執行的盤點流程,確認受影響的 Worker、CI 部署入口、帳號存取與資料揭露範圍,再決定是否關閉這個預設啟用的設定。

  5. 15. 遷移舊的 KV REST API 路徑

    Cloudflare Workers KV API 路徑即將淘汰:如何從 workers/namespaces 遷移

    Cloudflare Workers KV 已淘汰舊的 workers/namespaces REST API 路徑,並預計 2026 年 10 月 15 日停止支援。本文整理 endpoint 對照、程式碼盤點、驗證請求與遷移陷阱。

  6. 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。

Stage 04

線上出錯,從哪裡查起?

依錯誤類型選對方法:看請求內容、查 CPU 和記憶體限制,或用 traces 追跨服務的呼叫。

  1. 17. 找出重複讀取的 request body

    Cloudflare Workers request body 已被讀取怎麼修?先找第一個 reader 再 clone

    Cloudflare Workers 出現 request body already used 或 TypeError 時,先找出哪個 middleware 讀了 json、formData 或 text,再選擇單次解析、事前 clone 或串流轉送,避免重複讀取和不必要的記憶體負擔。

  2. 18. 分辨 CPU 與記憶體問題

    Cloudflare Workers Error 1102 怎麼查?先分 CPU 與記憶體

    Cloudflare Workers 遇到 Error 1102 時,先用 Workers Logs 分辨 CPU time 與 isolate 記憶體,再用輸入邊界、CPU profile 和串流處理定位問題,避免只改方案或盲目重寫 fetch。

  3. 19. 補上應用程式操作的 span

    Cloudflare Workers 自訂 span 怎麼用?比較 enterSpan 與 startSpan

    Cloudflare Workers 自訂 span 怎麼加?本文比較 enterSpan、startActiveSpan 與 startSpan 的生命週期,示範加入屬性和例外事件,並整理抽樣、錯誤處理與 trace ID 限制,適合補上應用程式內部操作的追蹤。

  4. 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 屬性與沒有資料時的排查。