NNext.js 中文网 GitHub

优化包打包

了解如何使用适用于 Turbopack 的 Next.js Bundle Analyzer 和适用于 Webpack 的 @next/bundle-analyzer 插件来分析和优化应用的服务端与客户端打包产物。

打包是将你的应用代码及其依赖项组合成针对客户端和服务端优化的输出文件的过程。更小的打包产物加载更快,可减少 JavaScript 执行时间,改善 Core Web Vitals,并降低服务端冷启动时间。

Next.js 会通过代码分割、tree-shaking 等技术自动优化打包产物。不过,在某些情况下你可能需要手动优化打包产物。

有两种工具可用于分析应用的打包产物:

本指南将引导你了解如何使用每种工具,以及如何优化大型打包产物。

Next.js Bundle Analyzer#

自 v16.1 起可用。你可以在专门的 GitHub 讨论中分享反馈,并在 turbopack-bundle-analyzer-demo.vercel.sh查看演示。

Next.js Bundle Analyzer 与 Turbopack 的模块图集成。你可以通过精确的导入追踪来检查服务端和客户端模块,从而更容易找到大型依赖项。打开交互式 Bundle Analyzer 演示即可探索模块图。

第 1 步:运行 Turbopack Bundle Analyzer#

要开始使用,请运行以下命令并在浏览器中打开交互式视图。

Terminal
npx next analyze
Terminal
yarn next analyze
Terminal
pnpm next analyze
Terminal
bunx next analyze

第 2 步:筛选和检查模块#

在界面中,你可以按路由、环境(客户端或服务端)和类型(JavaScript、CSS、JSON)进行筛选,或按文件搜索:

<Video caption="Next.js bundle analyzer 界面导览" src="/videos/bundle-analyzer.mp4" width={1708} height={1080} />

第 3 步:通过导入链追踪模块#

树状图将每个模块显示为一个矩形,模块的大小由矩形的面积表示。

点击某个模块可查看其大小、检查其完整的导入链,并准确查看它在你的应用中的使用位置:

第 4 步:将输出写入磁盘以便分享或比较#

如果你想与队友分享分析结果,或比较优化前/后的打包大小,可以跳过交互式视图,使用 --output 标志将分析保存为静态文件:

Terminal
npx next analyze --output
Terminal
yarn next analyze --output
Terminal
pnpm next analyze --output
Terminal
bunx next analyze --output

该命令会将输出写入 .next/diagnostics/analyze。你可以将此目录复制到其他地方以比较结果:

Terminal
cp -r .next/diagnostics/analyze ./analyze-before-refactor

导出分析数据#

自 v16.4 起可用。你可以在专门的 GitHub 讨论中分享反馈,并在 turbopack-bundle-analyzer-demo.vercel.sh查看演示。

使用 next analyze export 可将已保存的快照以 JSON Lines 格式流式输出,供脚本或 AI 工具使用,无需重新构建或启动服务器:

Terminal
npx next analyze --output --snapshot before
npx next analyze export --snapshot before > bundle-graph.jsonl
Terminal
yarn next analyze --output --snapshot before
yarn next analyze export --snapshot before > bundle-graph.jsonl
Terminal
pnpm next analyze --output --snapshot before
pnpm next analyze export --snapshot before > bundle-graph.jsonl
Terminal
bunx next analyze --output --snapshot before
bunx next analyze export --snapshot before > bundle-graph.jsonl

有关导出选项,请参阅 CLI 参考。

Bundle Analyzer 还有更多可用选项,完整列表请参阅 Next.js CLI 参考文档。

让你的 AI 智能体访问 bundle analyzer#

next-bundle-optimizer 技能可让你的 AI 智能体访问支撑 Turbopack bundle analyzer 的数据,自动识别影响网站初始加载性能的客户端大型打包产物的来源。

首先,安装该技能:

Terminal
npx skills add vercel/next.js --skill next-bundle-optimizer

然后向你的智能体发出提示。在仅审计模式下,它会生成报告而不做任何更改:

prompt
Use the next-bundle-optimizer skill to produce a report of the initial load performance of this site.

你还可以让智能体修复任何问题,它会根据发现的问题优化你的网站。或者,通过在提示中提供特定路由,让它专注于该路由。

适用于 Webpack 的 @next/bundle-analyzer#

@next/bundle-analyzer 是一个帮助你管理应用打包产物大小的插件。它会生成一份可视化报告,显示每个包及其依赖项的大小。你可以利用这些信息来移除大型依赖项、拆分或懒加载你的代码。

第 1 步:安装#

运行以下命令安装该插件:

bash · pnpm
pnpm add @next/bundle-analyzer
bash · npm
npm install @next/bundle-analyzer
bash · yarn
yarn add @next/bundle-analyzer
bash · bun
bun add @next/bundle-analyzer

然后,将 bundle analyzer 的设置添加到你的 next.config.js 中。

next.config.js
/** @type {import('next').NextConfig} */
const nextConfig = {}

const withBundleAnalyzer = require('@next/bundle-analyzer')({
  enabled: process.env.ANALYZE === 'true',
})

module.exports = withBundleAnalyzer(nextConfig)

第 2 步:生成报告#

运行以下命令来分析你的打包产物:

bash
ANALYZE=true npm run build
# or
ANALYZE=true yarn build
# or
ANALYZE=true pnpm build

报告将在你的浏览器中打开三个新标签页,你可以进行查看。

优化大型打包产物#

一旦你确定了某个大型模块,解决方案将取决于你的具体用例。以下是常见原因及修复方法:

包含大量导出的包#

如果你使用的某个包导出了数百个模块(如图标库和工具库),可以使用 next.config.js 文件中的 optimizePackageImports 选项来优化这些导入的解析方式。该选项只会加载你实际使用的模块,同时仍然让你可以方便地编写包含许多具名导出的导入语句。

next.config.js
/** @type {import('next').NextConfig} */
const nextConfig = {
  experimental: {
    optimizePackageImports: ['icon-library'],
  },
}

module.exports = nextConfig

小知识: Next.js 还会自动优化一些库,因此它们无需包含在 optimizePackageImports 列表中。请参阅受支持包的完整列表。

繁重的客户端工作负载#

客户端打包产物过大的一个常见原因是,在 Client Component 中执行了开销很大的渲染工作。这种情况常发生在那些仅用于将数据转换为 UI 的库上,例如语法高亮、图表渲染或 markdown 解析。

如果这些工作不需要浏览器 API 或用户交互,则可以在 Server Component 中运行。

在这个示例中,一个基于 prism 的高亮工具运行在 Client Component 中。即使最终输出只是一个 <code> 块,整个高亮库也会被打包进客户端 JavaScript bundle:

app/blog/[slug]/page.tsx
'use client'

import Highlight from 'prism-react-renderer'
import theme from 'prism-react-renderer/themes/github'

export default function Page() {
  const code = `export function hello() {
    console.log("hi")
  }`

  return (
    <article>
      <h1>Blog Post Title</h1>

      
      <Highlight code={code} language="tsx" theme={theme}>
        {({ className, style, tokens, getLineProps, getTokenProps }) => (
          <pre className={className} style={style}>
            <code>
              {tokens.map((line, i) => (
                <div key={i} {...getLineProps({ line })}>
                  {line.map((token, key) => (
                    <span key={key} {...getTokenProps({ token })} />
                  ))}
                </div>
              ))}
            </code>
          </pre>
        )}
      </Highlight>
    </article>
  )
}

这会增加打包体积,因为客户端必须下载并执行高亮库,即使结果只是静态 HTML。

相反,应将高亮逻辑移到 Server Component 中,并在服务端渲染最终的 HTML。客户端只会接收到渲染好的标记。

app/blog/[slug]/page.tsx
import { codeToHtml } from 'shiki'

export default async function Page() {
  const code = `export function hello() {
    console.log("hi")
  }`

  // Shiki 包在服务端运行,绝不会被打包到客户端。
  const highlightedHtml = await codeToHtml(code, {
    lang: 'tsx',
    theme: 'github-dark',
  })

  return (
    <article>
      <h1>Blog Post Title</h1>

      
      <pre>
        <code dangerouslySetInnerHTML={{ __html: highlightedHtml }} />
      </pre>
    </article>
  )
}

将特定包排除在打包之外#

在 Server Component 和 Route Handler 中导入的包会由 Next.js 自动打包。

你可以使用 next.config.js 中的 serverExternalPackages 选项将特定包排除在打包之外。

next.config.js
/** @type {import('next').NextConfig} */
const nextConfig = {
  serverExternalPackages: ['package-name'],
}

module.exports = nextConfig

未预打包的外部包#

默认情况下,导入到应用中的包不会被打包。如果外部包未预打包,例如从 monorepo 或 node_modules 导入时,这可能会影响性能。

要打包特定包,可以使用 next.config.js 中的 transpilePackages 选项。

next.config.js
/** @type {import('next').NextConfig} */
const nextConfig = {
  transpilePackages: ['package-name'],
}

module.exports = nextConfig

要自动打包所有包,可以使用 next.config.js 中的 bundlePagesRouterDependencies 选项。该选项默认为 false。

next.config.js
/** @type {import('next').NextConfig} */
const nextConfig = {
  bundlePagesRouterDependencies: true,
}

module.exports = nextConfig

将特定包排除在打包之外#

如果你发现某些包不应出现在打包产物中,可以使用 next.config.js 中的 serverExternalPackages 选项将特定包排除在自动打包之外:

next.config.js
/** @type {import('next').NextConfig} */
const nextConfig = {
  // 自动打包外部包:
  bundlePagesRouterDependencies: true,
  // 将特定包排除在打包之外:
  serverExternalPackages: ['package-name'],
}

module.exports = nextConfig

版本历史#

版本变更
v16.4.0新增 next analyze export 和 next-bundle-optimizer 技能。
Next.js 中文网