react.lazy 是 react 16.6+ 提供的动态导入 api,需配合 suspense 使用,支持按需加载组件、路由级懒加载、错误边界捕获及 webpack chunk 优化。

React.lazy 是 React 16.6+ 提供的 API,用于动态导入组件并实现按需加载(懒加载),必须配合 Suspense 使用。它的核心是包装一个返回 Promise 的 dynamic import() 表达式。
基本用法:用 lazy 包裹 import()
把原本静态导入的组件,改为使用 import() 动态导入,并传给 React.lazy:
const LazyComponent = React.lazy(() => import('./LazyComponent'));
注意:import() 必须是函数调用形式,不能写成变量或表达式提前求值(比如 const mod = import(...); lazy(() => mod) 是错的)。
必须搭配 Suspense 渲染异步组件
React.lazy 返回的是一个“懒组件”,它本身不处理加载状态。你需要用 <suspense fallback="..."></suspense> 包裹它,来指定加载中显示的内容:
function App() {
return (
<suspense fallback="<p">加载中...>
<lazycomponent></lazycomponent></suspense>
);
}
fallback 可以是任意 React 节点,比如骨架屏、Spinner 或文字提示。Suspense 还支持嵌套,可为不同区域设置不同 loading 状态。
配合路由实现页面级懒加载(如 React Router)
在路由场景中,常把每个路由组件都设为懒加载:
const Home = React.lazy(() => import('./pages/Home'));
const About = React.lazy(() => import('./pages/About'));
<p>function App() {
return (
<router><suspense fallback="<div">页面加载中>
<routes><route path="/" element="<Home"></route> />
<route path="/about" element="<About"></route> />
</routes></suspense></router>
);
}
</p>⚠️ 注意:不要在 element 中直接写 {<home></home>},要确保 <suspense></suspense> 包住整个 <routes></routes> 或至少包住懒组件的渲染位置。
进阶技巧:错误边界 + 加载状态优化
懒加载可能失败(如网络中断、模块不存在),建议加上 ErrorBoundary 捕获异常:
- 用自定义错误边界包裹
<suspense></suspense>,处理import()抛出的错误 - 避免重复加载失败:可在
lazy外加一层缓存逻辑(但通常 Webpack 已做模块缓存) - Webpack 会自动为
import()创建独立 chunk,可通过webpackChunkName注释控制文件名:React.lazy(() => import(/* webpackChunkName: "home" */ './pages/Home'))
这样生成的 chunk 文件更易识别,也方便做预加载或 CDN 分发。











