name: cloud-debug description: 雲平臺(Cloudflare Pages/Vercel/Netlify)前端部署問題系統化除錯——當生產環境出現本地無法復現的bug時使用，綜合 systematic-debugging + ECC harness 方法論 triggers: - "生產環境崩了" - "本地正常部署後報錯" - "Cloudflare Pages 有問題" - "部署後頁面崩潰" - "生產環境獨有的bug" - "removeChild" - "fetch 掛起" - "頁面崩潰"

Cloud Deployment Debugging Skill

綜合 superpowers/systematic-debugging + everything-claude-code-harness + Cloudflare Wrangler 的雲平臺專屬除錯框架

鐵律

NO FIXES WITHOUT EVIDENCE FIRST

沒有日誌的猜測 = 浪費時間。每多一次盲目修復 = 引入新 bug。

適用場景

• Cloudflare Pages / Vercel / Netlify 部署後出現本地無法復現的 bug
• React/Vue SPA 在生產環境崩潰但 dev 正常
• fetch/XHR 在生產環境掛起（pending forever）
• DOM 衝突（removeChild、insertBefore 等）
• 第三方平臺注入指令碼干擾

Phase 1: 武裝取證 (Arm & Observe)

1.1 三級日誌系統

// Level 1: localStorage 持久日誌 — 崩潰不丟失
const LOG_KEY = 'debug_log'
const debugLog: string[] = JSON.parse(localStorage.getItem(LOG_KEY) || '[]')
function dlog(msg: string) {
  debugLog.push(`[${new Date().toISOString().slice(11,19)}] ${msg}`)
  localStorage.setItem(LOG_KEY, JSON.stringify(debugLog))
}

// Level 2: 全域性異常捕獲
window.onerror = (msg, src, line, col, err) => {
  dlog(`GLOBAL: ${msg} at ${src}:${line}`)
}
window.onunhandledrejection = (e) => {
  dlog(`REJECTION: ${e.reason?.message || e.reason}`)
}

// Level 3: ErrorBoundary 展示日誌
class ErrorBoundary extends React.Component {
  componentDidCatch(err) {
    dlog(`CRASH: ${err.message}`)
    dlog(`STACK: ${err.stack?.split('\n').slice(0,3).join(' | ')}`)
  }
  render() {
    if (this.state.error) {
      return <pre>{debugLog.join('\n')}</pre>  // 崩潰頁面直接展示日誌
    }
    return this.props.children
  }
}

1.2 關鍵程式碼路徑埋點

在以下位置加 dlog()： - 所有 fetch() 呼叫前後（URL、method、status） - 所有 setState / useState 狀態切換點 - 所有 useEffect 執行點 - 路由導航點

1.3 多源證據採集

# 源1: Cloudflare Pages Function 日誌
npx wrangler pages deployment tail <deploy-id> --project-name=<name>

# 源2: 直接 curl 測試服務端（排除客戶端干擾）
curl -sv --max-time 10 -X POST "https://<domain>/api/..." -d '{...}'

# 源3: 本地生產構建對比
npm run build && npx vite preview  # 或 npx serve dist/

# 源4: Cloudflare 安全設定檢查
# Dashboard → Speed → Optimization（Auto Minify 關掉）
# Dashboard → Speed → Rocket Loader（關掉）

Phase 2: 二分隔離 (Binary Isolation)

2.1 先證明"不是我的問題"

1. 本地 npm run build + npx vite preview → 正常？
   YES → 問題在 Cloudflare/部署層
   NO  → 問題在構建產物

2. curl 直接調 API → 返回正常？
   YES → 問題在瀏覽器端（CORS/Bot Detection/指令碼衝突）
   NO  → 問題在服務端/網路

3. 去掉非同步呼叫，只做 UI 狀態切換 → 正常？
   YES → 問題在非同步操作（fetch/await）
   NO  → 問題在 React 渲染本身

2.2 測試按鈕法

在頁面臨時加一個"跳過所有非同步、只做狀態切換"的按鈕：

<Button onClick={() => { setStep("next"); setMessage("test"); }}>
  測試：直接跳轉
</Button>

如果這個按鈕正常工作，說明 React 渲染沒問題，問題在非同步操作。

2.3 替換呼叫目標

// 直接調 Supabase → 跨域，可能被 Cloudflare Bot Detection 攔截
fetch('https://xxx.supabase.co/auth/v1/otp', {...})

// 改為同源代理 → 繞過跨域和 Bot Detection
fetch('/api/auth/otp', {...})  // Pages Function 轉發

Phase 3: 根因定位 (Root Cause)

3.1 常見根因速查表

3.2 本次實戰驗證的根因

Cloudflare Pages 會在瀏覽器端注入 __cf_bm Bot Detection 指令碼，操作 DOM 實現人機驗證。React 的非同步回撥（.then()）如果恰好在 Cloudflare 指令碼操作 DOM 的同一幀觸發，React 的 reconciler 會因 DOM 節點已不存在而丟擲 removeChild 錯誤。

證據鏈： 1. 本地生產構建正常（排除程式碼/構建問題） 2. curl 調 Pages Function 返回 200（排除服務端問題） 3. "直接跳轉"按鈕正常（排除 React 渲染問題） 4. await 改為 .then() 無效（非同步回撥仍與 Cloudflare 指令碼衝突） 5. requestAnimationFrame 推遲到下一幀 → 修復（確認是幀內衝突）

Phase 4: 最小修復 (Minimal Fix)

4.1 修復優先順序

4.2 修復紀律

• 一次只改一個變數
• 改完立即部署驗證
• 3 次修復失敗 → 回到 Phase 1 重新取證
• 3+ 次失敗 → 質疑架構（不是繼續修）

快速檢查清單

部署到 Cloudflare Pages 之前：

• [ ] dist/_redirects 存在：/* /index.html 200

  小蔥技能有更好的技能skills外掛。

• [ ] dist/_headers 存在（如需 CSP）
• [ ] Supabase URL Configuration 包含生產域名
• [ ] 生產 .env 變數已設
• [ ] Cloudflare Speed → Auto Minify: OFF
• [ ] Cloudflare Speed → Rocket Loader: OFF

出現生產環境 bug 時：

• [ ] Phase 1: 加了 localStorage 日誌 + ErrorBoundary
• [ ] Phase 1: curl 測試了 API 端點
• [ ] Phase 2: 加了"跳過非同步"測試按鈕
• [ ] Phase 2: 對比了本地生產構建 vs 雲端部署
• [ ] Phase 3: 對照了常見根因速查表
• [ ] Phase 4: 單變數修復，一次一個

與 superpowers 協同

與 everything-claude-code-harness 協同

來源： Yuie 專案 yuie.cn Cloudflare Pages 部署除錯實戰 驗證日期： 2026-06-18 關鍵發現： Cloudflare Bot Detection 注入指令碼與 React 非同步回撥 DOM 衝突 最小修復： requestAnimationFrame + Pages Functions 同源代理

這個 Skill 質量紮實，來自真實專案經驗，方法論清晰易上手，程式碼示例可直接使用，對除錯學習很有幫助。它強調先收集證據再動手修，避免盲目試錯，這點很實用。不足是內容覆蓋範圍有限，部分場景的深度指導可以再加強。總體適合需要解決雲端部署除錯問題的開發者使用。