深入理解 React Lazy Loading：用 React.lazy 与 Suspense 构建高性能 React 应用

深入理解 React Lazy Loading：用 React.lazy 与 Suspense 构建高性能 React 应用

【免费下载链接】refineA React Framework for building internal tools, admin panels, dashboards & B2B apps with unmatched flexibility.项目地址: https://gitcode.com/GitHub_Trending/re/refine

导读

本文是一份关于 React 懒加载（Lazy Loading）的完整实战指南，源自 refine（一个用于构建内部工具、后台管理面板与 B2B 应用的 React 框架）官方博客的工程主题文章。全文将系统讲解懒加载的核心原理、React.lazy与动态import()的使用方式、Suspense回退 UI、错误边界（ErrorBoundary）、路由级与组件级代码分割，并延伸到 SEO 考量、测试策略与性能指标。读完本文，你将掌握如何在 React 应用（包括基于 refine 构建的管理后台）中按需加载代码块，显著降低首屏加载体积、改善用户体验。

什么是懒加载，为什么要用它？

懒加载（Lazy Loading）是软件工程中一种通用的性能优化策略，不仅适用于 Web 开发，同样可用于桌面端与移动端开发。它的核心思路是：只加载当前真正需要的资源，而不是一次性下载全部内容。这样用户无需等待所有资源下载完毕，就能开始使用网站或应用。

懒加载在应用层面的价值体现在多个方面：

• 性能提升（Improvement in Performance）：将首屏加载内容压到最小，页面加载更快，尤其适合内容量巨大的站点。用户不再需要等待全部资源下载完成才能操作。
• UI 元素按需加载（Loading UI Elements）：懒加载不只作用于页面，列表、图片等 UI 元素同样适用。例如一个详情页包含数百张图片，如果全部在初始阶段加载，性能会明显下降；改为在图片即将进入视口（viewport）前才加载，可以显著减少首屏的网络请求数量。
• 用户体验（User Experience）：更快的页面加载与响应时间能够提升用户留存率。相关研究显示，约有 95% 的用户在网页加载超过 2 秒后会选择离开。懒加载让关键内容“先加载、快加载”，从而留住用户。

懒加载的工作原理

懒加载的本质是削减初始页面加载时间。以一个博客网站为例：它包含首页（Home）、列表页（List）和详情页（Detail）三类页面，假设其体积分别为：

• 首页：39KB
• 列表页：90KB
• 详情页：88KB

如果加载首页时把三个页面全部加载，总共需要下载 217KB。而通过代码分割（code-splitting）把各页面拆成独立 bundle、按需加载，用户访问首页时只需下载 39KB，加载速度自然大幅提升。这不仅是页面级策略——当详情页中有数百张图片、需要向服务器发起上百个请求时，同样可以把图片加载推迟到它们即将滚入浏览器视口的那一刻。

React.lazy：按需动态加载组件

React.lazy()是 React 提供的懒加载工具，于React 16.6版本引入。它允许开发者把组件代码拆分为小块（chunk），按需加载，从而减少初始下载的代码量。lazy是 React 包导出的一个函数：

import { lazy } from "react";

// 或者

import React from "react"; React.lazy;

React.lazy底层依赖ES6（ECMAScript 6）动态导入（dynamic import），允许在运行时动态加载模块。以工具函数为例，普通静态导入是：

import { capitalizeFirstLetter } from "./utils";

要把它变为按需加载，改用动态import()：

import("./utils").then((utils) => { console.log(utils.capitalizeFirstLetter("nnamdi chidume")); });

这样utils会被从最终 bundle 中拆出，仅在需要时才加载。对于组件，先静态导入目标组件：

import LazyComponent from "./LazyComponent";

再调用React.lazy，传入一个调用import()并返回其 Promise 的回调函数，路径传给import()：

const LazyComponent = React.lazy(() => import("./LazyComponent"));

LazyComponent将从主 bundle 中拆分出来，页面初始加载时不会随主 bundle 一起下载，而是在它真正被使用时才加载。

以博客网站的首页为例，首页上有指向详情页的链接，懒加载详情页的写法如下：

import DetailPage from "./DetailPage"; const DetailPage = React.lazy(() => import("./DetailPage")); export const HomePage = () => { return ( <ul> {this.props.blogs.map((blog, index) => { return <DetailPage blog={blog} />; })} </ul> ); };

此时DetailPage被拆成独立 bundle，不再参与首页的初始加载。不过直接运行这段代码会报错：

React component suspended while rendering, but no fallback UI was specified.

原因在于：使用React.lazy加载的组件必须被Suspense包裹。

Suspense：为异步加载提供回退 UI

Suspense是 React 用于异步加载组件的特性，与React.lazy配合使用。它既可以在组件获取期间显示加载指示器，也可以在加载失败时渲染 fallback 组件。从 "react" 包导入：

import { Suspense } from "react";

将懒加载组件包裹在Suspense中：

<Suspense> <LazyComponent /> </Suspense>

但这并不是好的 UX 实践——用户完全不知道有一个组件正在加载。因此需要借助Suspense的fallback属性，在懒加载组件尚未下载完成时展示一个 UI 提示。fallback可以接收字符串或任意 JSX：

<Suspense fallback={"Loading..."}> <LazyComponent /> </Suspense>

<Suspense fallback={<div>Loading...</div>}> <LazyComponent /> </Suspense>

捕获加载错误：ErrorBoundary

使用React.lazy时，必须处理可能出现的加载错误（例如网络错误）。做法是把包含懒加载组件的Suspense再包进一个ErrorBoundary（错误边界）组件中。错误边界在 React 中的作用类似于 JavaScript 的 try-catch：它捕获组件树中的错误，避免整个应用崩溃。

一个典型的错误边界组件：

class ErrorBoundary extends React.Component { constructor(props) { super(props); this.state = { hasError: false }; } static getDerivedStateFromError(error) { return { hasError: true }; } componentDidCatch(error, errorInfo) { logService(error, errorInfo); } render() { return this.state.hasError ? ( <h1>Something went wrong.</h1> ) : ( this.props.children ); } }

当被包裹的组件树抛出错误时，应用不会崩溃，而是就地渲染Something went wrong.。组合使用方式：

<ErrorBoundary> <Suspense fallback={<div>Loading...</div>}> <LazyComponent /> </Suspense> </ErrorBoundary>

路由级代码分割（Route-based Code Splitting）

React 组件分为两类：路由级组件（Route-based）与组件级组件（Component-based）。不需要（也不应该）对应用中所有组件都做懒加载——过度懒加载反而会引发严重问题。何时、对哪个组件做懒加载的判断并不容易，但可以确定的是：路由级组件是必须懒加载的对象。

路由级组件是用户导航到指定 URL 时才加载的组件，即基于 react-router 配置的页面。原始写法：

import React from "react"; import { BrowserRouter as Router, Routes, Route } from "react-router-dom"; import Home from "./Home"; import About from "./About"; const App = () => ( <Router> <Routes> <Route path="/" element={<Home />} /> <Route path="/about" element={<About />} /> </Routes> </Router> );

这里/与/about两个路由分别加载Home与About页面，二者都是典型的路由级组件，非常适合懒加载。改造后：

import React, { Suspense, lazy } from "react"; import { BrowserRouter as Router, Routes, Route } from "react-router-dom"; const Home = React.lazy(() => import("./Home")); const About = React.lazy(() => import("./About")); const App = () => ( <Router> <Suspense> <Routes> <Route path="/" element={<Home />} /> <Route path="/about" element={<About />} /> </Routes> </Suspense> </Router> );

现在Home与About被拆分为各自独立的 bundle，仅在对应路由被访问时加载，应用整体 bundle 体积与页面加载时间都会显著下降。

组件级代码分割（Component-based Code Splitting）

组件级组件是不挂在页面路由上、用于展示应用中 UI 区块的普通组件，本文前述的大部分示例都属于这一类。最适合做代码分割的组件是 Modal（弹窗）与 Aside（侧边栏），因为它们在网页加载时就被急切（eagerly）加载了，而实际使用频率可能很低。

与此相反，Header、下拉菜单、按钮这类组件不应懒加载——它们是最常用、最容易被立即需要的 UI 元素，懒加载反而会引入不必要的加载延迟。

懒加载与 SEO 的考量

懒加载通过只在需要时加载必要资源，能显著改善网站性能与用户体验；但同时也要保证搜索引擎能有效抓取内容。以下是需要留意的几个要点：

• 确保关键内容可访问（Ensure Critical Content is Accessible）：不要懒加载重要内容，尤其是首屏（above-the-fold）内容，保证搜索引擎从一开始就能看到页面的关键部分。
• 使用正确的 HTML 标记（Use Proper HTML Markup）：即使对图片做懒加载，仍要使用标准的<img>标签——可将src设为占位图，用data-src（或类似属性）保存真实图片 URL，确保搜索引擎能正确解析与索引图片。
• Intersection Observer API：用它实现懒加载是一种轻量、快速监测文档中元素可见性的方式，也符合支持 JavaScript 的主流搜索引擎的抓取逻辑。
• 提供回退方案（Provide Fallbacks）：始终为不支持懒加载的用户或爬虫提供回退，例如渲染基础版本内容，或保证无 JavaScript 环境下内容依然可用。
• 关注搜索引擎抓取情况（Watch out for search engine crawls）：借助 Google Search Console 等工具检查页面的抓取与索引情况；如果发现重要内容缺失，很可能是懒加载实现不当。正确的懒加载可以在性能提升与 SEO 之间取得平衡。

测试懒加载组件

懒加载组件需要专门的测试策略，才能确保其正确、高效地加载：

• 配置测试环境（Setting Up the Test Environment）：确保测试框架（如 Jest）支持懒加载，即能配合 React 的Suspense与React.lazy工作。
• Mock 动态导入（Mocking Dynamic Imports）：测试时可以通过 mock 动态导入，控制组件的加载时机与方式。
• 测试中使用 Suspense：像应用代码一样，在测试中用Suspense包裹懒加载组件。

下面是一个基于 Jest 与 React Testing Library 的完整示例：

// LazyComponent.js import React from 'react'; const LazyComponent = () => { return <div>Lazy Loaded Component</div>; }; export default LazyComponent; // App.js import React, { Suspense, lazy } from 'react'; const LazyComponent = lazy(() => import('./LazyComponent')); const App = () => { return ( <Suspense fallback={<div>Loading...</div>}> <LazyComponent /> </Suspense> ); }; export default App; // App.test.js import React from 'react'; import { render, screen } from '@testing-library/react'; import '@testing-library/jest-dom/extend-expect'; import App from './App'; test('loads and displays lazy component', async () => { render(<App />); // Check for fallback content expect(screen.getByText('Loading...')).toBeInTheDocument(); // Wait for lazy component to load const lazyElement = await screen.findByText('Lazy Loaded Component'); expect(lazyElement).toBeInTheDocument(); });

测试先断言 fallback 内容Loading...出现，再通过findByText异步等待懒加载组件真正渲染完成——这正是懒加载组件测试的核心流程。

性能指标与测量工具

为了量化懒加载带来的收益，需要关注以下关键性能指标（Core Web Vitals 体系）：

• First Contentful Paint（FCP）：屏幕上绘制出任何内容所花费的时间。懒加载减小初始 bundle 体积，从而改善 FCP。
• Time to Interactive（TTI）：应用真正可交互所需时间。初始阶段只加载必要内容有助于缩短 TTI。
• Largest Contentful Paint（LCP）：页面最大内容元素变为可见所需时间，可通过优化懒加载来改善。
• Cumulative Layout Shift（CLS）：页面生命周期中所有非预期布局偏移的总分。图片与组件懒加载到位后往往减少布局偏移，CLS 因此更优。

常用的测量工具包括：

• Lighthouse：Chrome DevTools 内置功能，可审计性能、无障碍、最佳实践与 SEO。
• WebPageTest：提供更深入的性能细节，含胶片视图（filmstrip）与瀑布图（waterfall charts）。
• Google Analytics：通过自定义指标持续追踪性能数据随时间的变化。
• Performance API：浏览器内置的 Performance API，可在应用代码中测量精确的时间点。

从源码看懒加载在 refine 文档站中的实践

本文出自 refine 官方博客。refine 是一个用于构建内部工具、后台面板、仪表盘与 B2B 应用的 React 框架，其配套文档站（本仓库documentation/目录，基于 Docusaurus 构建）本身就把懒加载的多种形态落到了实处，可以作为参照：

• 依赖层面的 React 版本支持：文档站使用react: "^17.0.2"（见 documentation/package.json），而核心包@refinedev/core支持react: "^18.0.0 || ^19.0.0"（见 packages/core/package.json）。React.lazy自 React 16.6 起即为稳定特性，因此在这些版本范围内均可放心使用。
• 动态 import 的真实用例：文档站的搜索栏在需要展示搜索弹窗时，通过动态import()延迟加载 DocSearch 的弹窗模块、样式与本地样式文件（见 documentation/src/theme/SearchBar/index.tsx）。这正是“非首屏关键资源按需加载”思路的落地。
• 原生图片懒加载实践：文档站的自定义图片组件为<img>设置了loading="lazy"属性（见 documentation/src/components/image/index.tsx），博客文章卡片同样如此（见 documentation/src/theme/BlogPostItem/index.js），利用浏览器原生能力对图片做懒加载——与本文“图片进入视口前再加载”的原则完全一致。

结语

我们从懒加载的定义与价值出发，理解了它如何减少首屏加载体积、改善用户体验；随后深入React.lazy函数与动态import()的用法，学习了Suspense回退 UI 与 ErrorBoundary 错误捕获；再分别针对路由级组件与组件级组件讨论了代码分割的取舍，并延伸覆盖了 SEO 考量、测试策略与性能指标测量。

React.lazy是 React 中让组件按需加载的强大特性：组件只在真正需要时才被加载，从而提升应用整体性能。结合Suspense的 fallback 提示与 ErrorBoundary 的兜底处理，再配合正确的代码分割粒度选择，你可以在任何 React 项目——包括基于 refine 构建的管理后台——中稳定地落地一套高效的懒加载方案。

【免费下载链接】refineA React Framework for building internal tools, admin panels, dashboards & B2B apps with unmatched flexibility.项目地址: https://gitcode.com/GitHub_Trending/re/refine