遇到 React 白屏报错时，建议先排查运行时环境：执行npm list react react-dom确认版本是否一致，检查window.React是否已正确加载，再定位Qoder生成代码的语义断点，最后通过Alt+Enter、qoder wake或重置上下文完成修复。
当你使用Qoder生成React代码后，如果出现页面白屏、控制台报错、组件无法渲染，或状态更新不生效，通常说明生成逻辑与当前项目环境之间存在兼容性问题。这类故障往往不只是简单的语法错误，更常见的原因是跨框架语义理解偏差、依赖版本不匹配，或运行时上下文缺失等多种因素叠加导致。
先确认是否是React运行时环境异常
这一步先暂时绕开Qoder本身的生成逻辑，直接检查底层环境——如果React运行时都没有正常启动，那么生成出来的代码再正确也无法生效。
在终端执行 npm list react react-dom，确认输出中两个包的版本是否一致：例如 react 18.x 应搭配 react-dom 18.x；如果看到 UNMET PEER DEPENDENCY，或者主版本差超过1级（如 react@19.0.0 + react-dom@18.2.0），应立即执行 npm install react@18.3.1 react-dom@18.3.1 进行强制对齐。
接着打开浏览器开发者工具，进入 Console 标签页，输入 window.React 并回车：如果返回 undefined，通常说明 React 没有正确挂载到运行环境中。这种情况大多与 Webpack 或 Vite 配置里的 alias、externals 设置错误 有关，导致 react 包被错误排除或屏蔽。此时应重点检查 vite.config.ts 中是否误写了 external: ['react']，以及 webpack.config.js 里的 externals 配置是否没有正确处理 react。
定位Qoder生成代码的语义断点
React报错信息中带有文件路径和行号的红色提示，通常就是Qoder生成代码出现问题的关键位置。不要急着直接修改，建议先完成以下三步排查：
第一步：点击控制台报错中的文件名和行号，跳转到源码；然后右键该文件标签页 → “Reveal in Explorer”，确认这个文件确实来自Qoder生成目录（路径包含 qoder-output 或 .qoder/cache）；【如果路径实际指向 node_modules 或 src/utils，则说明Qoder可能把补丁打到了错误位置】
第二步：在报错行上方插入 console.log('DEBUG:', { yourVariable });，重新运行后观察输出值是否为 undefined 或 null——如果确实如此，通常意味着Qoder生成的 hook 调用顺序违反了 Rules of Hooks（例如在条件判断中调用 useState），这时必须将 hook 提前到函数顶部统一声明。
第三步：先复制报错堆栈最顶部那一行，例如 at Button.jsx:12:3。然后在 VSCode 中按 Ctrl+P，输入 @Button.jsx:12，即可快速精确地定位到生成代码的第 12 行。定位后，再对照最新 React 官方文档中对应 API 的签名，重点检查参数个数、参数类型、参数顺序是否一致。例如本应写成 useEffect(fn, [])，如果被错误生成成 useEffect(fn, [dep])，就可能导致无限循环渲染。
用Qoder内置诊断快速修复
方法一：Alt+Enter 触发实时修复
将光标停留在报错行任意位置 → 按 Alt+Enter（Windows/Linux）或 ⌥⏎（macOS）→ 在弹出的菜单中选择以 Fix 'React Hook called conditionally' 或 Add missing dependency array 开头的选项 → 确认并应用修复。
方法二：qoder wake 诊断运行时异常
复制完整报错堆栈（包括 TypeError 行和 at ComponentName 行）→ 打开终端 → 执行 qoder wake diagnose --log "TypeError: Cannot read properties of null" → 等待45秒左右 → CLI 会返回可直接粘贴的补丁代码块，注意重点检查补丁中 useState 的初始值是否从 undefined 调整为 null 或空对象。
方法三：重置上下文后重新生成
关闭所有编辑器标签页 → 进入IDE菜单 File → Close Project → 删除 C:Users[用户名].lingmacontext（Windows）或 ~/.lingma/context（macOS）→ 重启IDE → 重新打开项目 → 等待右下角Qoder图标显示 【Ready】 后，再重新触发代码生成。