Cloudflare Workers Local Explorer 怎麼用？用 wrangler dev 看 bindings、logs 與 traces
本機 Worker 出錯時，最浪費時間的情境不是沒有 log，而是你必須另外寫腳本查 KV、手動印出 D1 查詢，還要猜是哪一個 binding 先失敗。Cloudflare 的 Local Explorer 把這些操作放進 wrangler dev 的瀏覽器介面，可以直接看本機資料、invocation logs 與 trace。
它適合拿來回答一個很具體的問題：這次 request 是在 handler、外部 fetch，還是哪一個 binding 操作失敗？ 它不是 production dashboard 的替代品，也不會讓本機資料自動等於 production 資料。
先確認 Wrangler 版本
官方文件目前要求：Wrangler 4.118.0 以上，或 Cloudflare Vite plugin 1.50.0 以上。先檢查專案實際執行的 CLI，而不是只看全域安裝版本：
pnpm exec wrangler --versionpnpm list wrangler --depth 0如果專案沒有安裝 Wrangler，先在專案內加入固定版本；官方也建議把 Wrangler 安裝在專案中，讓團隊和 CI 使用同一個版本：
pnpm add -D wrangler@latest不要把 npx wrangler 解析到的 latest 當成專案真正的版本。查不到 Local Explorer 時，第一個要排除的就是 CLI 版本和執行目錄。
用 wrangler dev 開啟 Local Explorer
在有 Wrangler 設定檔的 Worker 專案執行：
pnpm exec wrangler dev啟動後在終端機按 e，Wrangler 會開啟 Local Explorer。它也會依照設定檔自動偵測 binding；不需要為了查看資料另外寫一個 debug endpoint。
使用 Cloudflare Vite plugin 時，則直接在同一個 dev server 的 host 與 port 開啟：
/cdn-cgi/explorer本機 URL 的 port 可能不是 8787，以終端機顯示的 dev server 位址為準。這個路徑是本機開發工具，不是要提交到網站或 production route 的頁面。
五種 binding 可以直接檢查什麼
Local Explorer 目前支援的操作範圍不完全相同，先分清楚「查看」與「修改」：
| Binding | 可查看 | 可修改或執行 |
|---|---|---|
| KV | keys、value、metadata | 建立、更新、刪除 key-value |
| R2 | object、metadata | 上傳與刪除物件 |
| D1 | tables、rows | SQL 查詢與資料異動 |
| Durable Objects SQLite | tables、rows | SQL 查詢與資料異動 |
| Workflows | instance、status、step history | 觸發或重試執行 |
D1 與 SQLite-backed Durable Objects 還有 SQL Studio。這能協助確認「migration 沒套用」、「row 根本沒有寫入」或「第二次 binding call 才失敗」等問題，但 SQL Studio 的修改仍然是真實的本機資料異動，執行前要先選對 database。
用 trace 找出第一個失敗的操作
假設 Worker 先寫 D1，再呼叫另一個 API，最後回傳 500。只看瀏覽器的 500 不夠，建議按這個順序排查：
- 先送出一個可重現的 request，記下時間、method 和 path。
- 在 Logs 搜尋
console.*輸出與錯誤文字，確認這次 invocation。 - 打開同一個 invocation 的 trace，依序看 handler、outbound
fetch與 binding span。 - 找出第一個 status 或 error 改變的 span，再回到該 binding 的資料或程式碼。
- 修正後重送同一個 request，確認 trace 不只是「沒有錯誤」，而是走過預期的資料路徑。
Local Explorer 會自動捕捉 invocation、binding operation、時間與 console output，不需要在每一個 call 旁邊加暫時性的 console.log。這對 Cloudflare Workers integration test harness 的測試失敗也有幫助：先用 trace 確認哪個 binding 出錯，再決定要補測試資料還是修 Worker。
需要自動化時，改用 Local Explorer API
Local Explorer 也提供 API，可以先拿 OpenAPI specification：
curl http://localhost:8787/cdn-cgi/explorer/api如果 Wrangler 使用其他 port，替換成終端機顯示的位址。AI coding agent 或本機腳本可以先讀 schema，再依 endpoint 查詢 traces、logs 或 binding 狀態；不要直接猜測未文件化的 API 路徑。
Cloudflare 文件示範的 agent hint 會指向 /cdn-cgi/explorer/api/local/observability/query，但正式自動化仍應以目前 dev session 回傳的 OpenAPI schema 為準。這個 API 可讓 agent 讀取或修改本機資料，因此應限制在本機開發環境，不要把 dev server 直接暴露到公開網路。
Local Explorer 和 production dashboard 怎麼分工
- Local Explorer：驗證本機 binding、測試資料、單次 request trace 與 logs。
- Workers Logs／Traces：檢查已部署 Worker 的真實流量、遠端服務與 production observability。
- 測試 harness：在 CI 重現 request、binding state 與回歸情境。
如果本機是 wrangler dev --remote，程式和遠端 binding 的行為會接近 Cloudflare 網路，但任何寫入、Workflow retry 或資料異動都可能碰到遠端資源。排錯流程仍要先確認目前是 local 還是 remote，不要把本機資料操作誤當成 production rollback。
結論：先用 trace 定位，再用資料介面驗證
Local Explorer 的價值不在多一個 dashboard，而是把 request、binding 操作和本機資料放在同一個除錯路徑。先把 Wrangler 固定在 4.118.0 以上，使用 wrangler dev 重現，從 trace 找第一個失敗的 span，再用 KV、D1、R2 或 Workflow 介面驗證狀態；要自動化時先讀 API schema，並保留 local／remote 的邊界。
Q: Local Explorer 找不到 D1 資料，是不是 migration 失敗？
A: 不一定。先確認 Worker 使用的 Wrangler 設定與 database binding，再確認目前是 local 還是 remote。Local Explorer 預設查看本機模擬的 binding；它不會自動載入 production D1 的資料。
Q: 需要在 Worker 裡加 console.log 才能看到 trace 嗎？
A: 不需要。Local Explorer 會自動捕捉 invocation、binding operation 和 timing；console.* 仍會出現在 Logs。只有要記錄業務欄位或自訂狀態時，才應加入有意義且不含機密的 log。
Q: 可以用 Local Explorer API 讓 agent 自動改資料嗎？
A: 技術上可以，但先把它視為具有寫入能力的本機開發 API。讓 agent 先讀 OpenAPI schema，限制操作範圍與資料庫，並確認 dev server 沒有暴露到公開網路；不要把這個流程直接套到 production credential。
參考資料：
Cloudflare Workers Docs：Local Explorer
Cloudflare Changelog：AI agents can debug Workers with local tracing
回報錯字、失效連結，或告訴我你想看的延伸主題。