云端部署调试

要解决的问题

部署到 Cloudflare Pages、Vercel 或 Netlify 之后，一些 bug 在本地怎么都复现不了：fetch 或 XHR 请求永远停在 pending，React/Vue SPA 在生产环境崩溃但 dev 正常，DOM 操作抛出 removeChild、insertBefore 异常，或者页面白屏、静态资源 404。根因经常不在业务代码里，而在平台注入脚本、构建压缩、路由配置或安全响应头之间。这个技能针对这类线上问题，把调试过程拆成可执行的阶段，避免在没有日志的情况下反复盲目修复。

四阶段调试流程

• Phase 1 武装取证：先建立 localStorage 日志和 ErrorBoundary，在 fetch()、setState、useEffect、路由导航等关键路径埋点，再用 curl 测试 API 端点、对比本地生产构建和云端部署结果。
• Phase 2 二分隔离：证明问题是否来自平台或异步流程。例如临时加一个“跳过所有异步、只做状态切换”的按钮；按钮正常，说明 React 渲染没问题，故障更可能位于异步操作或外部脚本交互。
• Phase 3 根因定位：对照常见症状速查表排查 fetch 挂起、removeChild 崩溃、生产 JS 语法错误、白屏和第三方 API 不通。实战中已确认 Cloudflare Pages 注入的 __cf_bm Bot Detection 脚本可能与 React 异步回调争用 DOM，触发帧内冲突。
• Phase 4 最小修复：优先尝试 requestAnimationFrame(() => setState(...)) 处理 DOM 冲突；必要时再考虑同源 Pages Function 代理、移除 StrictMode、关闭 Auto Minify/Rocket Loader 或改用纯 REST API。每次只改一个变量，改完立即部署验证；连续失败应回到取证阶段，而不是继续叠加修改。

验证记录与适用边界

该框架来自 Yuie 项目 yuie.cn 的 Cloudflare Pages 部署调试实战，验证日期为 2026-06-18。适用场景限定于云端部署后出现的异步请求、SPA 渲染、DOM 冲突、平台脚本注入和部署配置异常；它不替代普通的单元测试或前端开发流程。使用时应先确认证据链完整，再选择对应修复项；在未证实根因前关闭 Cloudflare 优化功能，本身也是一次变量修改。