如何懒加载 Client Components 和库
懒加载导入的库和 React 组件,以提升应用程序的整体加载性能。
懒加载在 Next.js 中通过减少渲染路由所需的 JavaScript 数量,帮助提升应用的初始加载性能。
它让你可以延迟加载 Client Component 和导入的库,只在需要时才将它们包含在客户端 bundle 中。例如,你可能希望延迟加载一个模态框,直到用户点击打开它。
在 Next.js 中有两种方式可以实现懒加载:
- 使用
next/dynamic进行动态导入 - 结合 Suspense 使用
React.lazy()
默认情况下,Server Component 会自动进行代码分割,你可以使用流式渲染逐步将 UI 片段从服务端发送到客户端。懒加载适用于 Client Component。
next/dynamic#
next/dynamic 是 React.lazy() 和 Suspense 的组合。它在 app 和 pages 目录中的行为一致,以支持增量迁移。
示例#
导入 Client Component#
'use client'
import { useState } from 'react'
import dynamic from 'next/dynamic'
// Client Component:
const ComponentA = dynamic(() => import('../components/A'))
const ComponentB = dynamic(() => import('../components/B'))
const ComponentC = dynamic(() => import('../components/C'), { ssr: false })
export default function ClientComponentExample() {
const [showMore, setShowMore] = useState(false)
return (
<div>
<ComponentA />
{showMore && <ComponentB />}
<button onClick={() => setShowMore(!showMore)}>Toggle</button>
<ComponentC />
</div>
)
}注意: 当 Server Component 动态导入 Client Component 时,目前不支持自动代码分割。
跳过 SSR#
使用 React.lazy() 和 Suspense 时,Client Component 默认会被预渲染(SSR)。
注意:
ssr: false选项仅适用于 Client Component,请将其移入 Client Component 以确保客户端代码分割正常工作。
如果要为 Client Component 禁用预渲染,可以将 ssr 选项设为 false:
const ComponentC = dynamic(() => import('../components/C'), { ssr: false })导入 Server Component#
如果动态导入 Server Component,只有作为该 Server Component 子级的 Client Component 会被懒加载,而 Server Component 本身不会。 在 Server Component 中使用它时,这还有助于预加载 CSS 等静态资源。
import dynamic from 'next/dynamic'
// Server Component:
const ServerComponent = dynamic(() => import('../components/ServerComponent'))
export default function ServerComponentExample() {
return (
<div>
<ServerComponent />
</div>
)
}注意: Server Component 中不支持
ssr: false选项。如果尝试在 Server Component 中使用它,会看到错误。 Server Component 中不允许将ssr: false与next/dynamic一起使用。请将其移入 Client Component。
加载外部库#
可以使用 import() 函数按需加载外部库。此示例使用外部库 fuse.js 进行模糊搜索。只有在用户在搜索输入框中输入内容后,才会在客户端加载该模块。
'use client'
import { useState } from 'react'
const names = ['Tim', 'Joe', 'Bel', 'Lee']
export default function Page() {
const [results, setResults] = useState()
return (
<div>
<input
type="text"
placeholder="Search"
onChange={async (e) => {
const { value } = e.currentTarget
// 动态加载 fuse.js
const Fuse = (await import('fuse.js')).default
const fuse = new Fuse(names)
setResults(fuse.search(value))
}}
/>
<pre>Results: {JSON.stringify(results, null, 2)}</pre>
</div>
)
}添加自定义加载组件#
'use client'
import dynamic from 'next/dynamic'
const WithCustomLoading = dynamic(
() => import('../components/WithCustomLoading'),
{
loading: () => <p>Loading...</p>,
}
)
export default function Page() {
return (
<div>
<WithCustomLoading />
</div>
)
}导入具名导出#
要动态导入具名导出,可以从 import() 函数返回的 Promise 中将其返回:
'use client'
export function Hello() {
return <p>Hello!</p>
}import dynamic from 'next/dynamic'
const ClientComponent = dynamic(() =>
import('../components/hello').then((mod) => mod.Hello)
)魔法注释#
Next.js 支持魔法注释,用于控制打包器如何处理动态导入。这些注释适用于动态 import()、require()、require.resolve() 和 new Worker() 表达式。
小知识: 魔法注释不适用于静态
import语句(import x from 'y')。它们仅适用于动态表达式。
webpackIgnore / turbopackIgnore#
使用这些注释可以跳过对动态导入的打包。导入表达式将在输出中保持原样,适用于仅在运行时使用的模块:
// 跳过打包 - 导入在运行时发生
const runtime = await import(/* webpackIgnore: true */ 'runtime-module')
// Turbopack 专用变体
const plugin = await import(/* turbopackIgnore: true */ pluginPath)
// 同样适用于 require
const mod = require(/* webpackIgnore: true */ 'runtime-module')turbopackOptional(仅 Turbopack)#
当模块可能不存在时,可使用此注释来抑制构建错误。如果模块缺失,导入仍会在运行时抛错:
// 如果 './optional-feature' 不存在,不会出现构建错误
// 如果执行,运行时将抛出 MODULE_NOT_FOUND
const feature = await import(/* turbopackOptional: true */ './optional-feature')
// 同样适用于 require
const mod = require(/* turbopackOptional: true */ './optional-module')这适用于以下场景:
- 可能未安装的条件性功能
- 模块为可选插件的系统
- 某些文件可能尚不存在的渐进式迁移
小知识: 不支持
webpackOptional。使用 Turbopack 时请改用turbopackOptional。
next/dynamic#
next/dynamic 是 React.lazy() 和 Suspense 的组合。它在 app 和 pages 目录中的行为一致,以支持增量迁移。
在下面的示例中,通过使用 next/dynamic,header 组件将不会包含在页面的初始 JavaScript bundle 中。页面会先渲染 Suspense 的 fallback,当 Suspense 边界解析完成后再渲染 Header 组件。
import dynamic from 'next/dynamic'
const DynamicHeader = dynamic(() => import('../components/header'), {
loading: () => <p>Loading...</p>,
})
export default function Home() {
return <DynamicHeader />
}小知识:在
import('path/to/component')中,路径必须显式写出。它不能是模板字符串或变量。此外,import()必须位于dynamic()调用内部,这样 Next.js 才能将 webpack bundle / 模块 id 与特定的dynamic()调用匹配,并在渲染前预加载它们。dynamic()不能在 React 渲染期间使用,因为它需要在模块顶层标记才能进行预加载,类似于React.lazy。
示例#
使用具名导出#
要动态导入具名导出,可以从 import() 返回的 Promise 中将其返回:
export function Hello() {
return <p>Hello!</p>
}
// pages/index.js
import dynamic from 'next/dynamic'
const DynamicComponent = dynamic(() =>
import('../components/hello').then((mod) => mod.Hello)
)不使用 SSR#
要在客户端动态加载组件,可以使用 ssr 选项禁用服务端渲染。如果外部依赖或组件依赖 window 等浏览器 API,这很有用。
'use client'
import dynamic from 'next/dynamic'
const DynamicHeader = dynamic(() => import('../components/header'), {
ssr: false,
})使用外部库#
此示例使用外部库 fuse.js 进行模糊搜索。只有在用户在搜索输入框中输入内容后,才会在浏览器中加载该模块。
import { useState } from 'react'
const names = ['Tim', 'Joe', 'Bel', 'Lee']
export default function Page() {
const [results, setResults] = useState()
return (
<div>
<input
type="text"
placeholder="Search"
onChange={async (e) => {
const { value } = e.currentTarget
// 动态加载 fuse.js
const Fuse = (await import('fuse.js')).default
const fuse = new Fuse(names)
setResults(fuse.search(value))
}}
/>
<pre>Results: {JSON.stringify(results, null, 2)}</pre>
</div>
)
}