React 18启用StrictMode后页面空白，无控制台报错如何排查？

API 探路者

2026-8-21

排查 React 18 StrictMode 导致白屏的问题

React 18 的 StrictMode 在开发环境下会重复执行组件的挂载/卸载流程、钩子函数和初始化逻辑，目的是检测潜在的副作用问题。移除 StrictMode 后应用恢复正常，说明你的代码或依赖库中存在无法兼容这种重复执行的逻辑。以下是具体排查步骤：

检查 useEffect 钩子的副作用与清理逻辑
StrictMode 会触发 useEffect 的清理函数后再次执行副作用。如果你的 useEffect 没有正确实现清理，或者依赖的第三方库无法重复初始化，就可能导致组件失效。例如：
```
// 错误示例：未清理第三方实例，重复初始化导致冲突
useEffect(() => {
  const map = new MapLibrary('#map');
  // 缺少 return () => map.destroy();
}, []);
```
确保每个有副作用的 useEffect 都有对应的清理函数，且逻辑支持重复执行。
审查组件生命周期方法中的副作用
传统类组件的 componentDidMount 在 StrictMode 开发环境中会被调用两次。如果这些方法中存在修改全局状态、订阅事件未清理等操作，会导致状态异常。比如在 componentDidMount 中直接修改全局变量而未在 componentWillUnmount 中恢复，重复执行后会引发逻辑错误。
检查 useState 初始化函数的纯净性
useState 的初始化函数应该是纯函数（无副作用），但 StrictMode 会重复执行它。如果初始化函数中包含修改全局变量、调用异步 API（不推荐）或其他副作用，会导致初始状态异常，进而引发组件渲染失败。
排查第三方依赖兼容性
部分老旧的第三方库（如状态管理工具、UI 组件库、动画库）可能未适配 React 18 的 StrictMode 机制。尝试逐步移除或替换第三方组件，定位到引发问题的依赖后，查看其是否有更新版本支持 React 18，或者寻找替代方案。
使用 React DevTools 分析组件树
即使控制台无报错，也可以通过 React DevTools 查看组件树状态。确认 <App /> 及其子组件是否被正确挂载，检查组件的 props、state 是否符合预期。如果某组件在 StrictMode 下状态为 null/undefined，可能就是问题所在。
启用控制台警告过滤
确保浏览器开发者工具的「Warnings」选项已开启。React 18 StrictMode 会针对不安全的 API、未清理的副作用等发出警告，这些警告可能被你忽略，而它们正是定位问题的关键线索。
检查全局状态或变量的修改逻辑
如果应用依赖全局变量或单例模式，StrictMode 的重复执行可能会破坏其状态一致性。例如，全局计数器被重复递增，导致后续逻辑判断错误，进而使组件无法正常渲染。

内容的提问来源于stack exchange，提问作者vanillaSugar