Next.js 旨在提供卓越的开发者体验。随着应用程序的增长，你可能会发现在本地开发期间编译时间变慢。本指南将帮助你识别并解决常见的编译时性能问题。

本地开发与生产环境

使用 next dev 的开发过程与 next build 和 next start 不同。

next dev 会在你打开或导航到应用程序中的路由时编译它们。这使你无需等待应用程序中的每个路由都编译完成即可启动开发服务器，这既更快又占用更少的内存。运行生产构建会应用其他优化，例如文件缩小化和创建内容哈希，这些在本地开发中是不需要的。

提升本地开发性能

1. 检查电脑的杀毒软件

杀毒软件会减慢文件访问速度。虽然这在 Windows 机器上更常见，但对于任何安装了杀毒工具的系统来说，这都可能是一个问题。

在 Windows 上，你可以将项目添加到 Microsoft Defender Antivirus exclusion list 中。

1. 打开 “Windows 安全中心” 应用，然后选择 “病毒与威胁防护” → “管理设置” → “添加或删除排除项”。
2. 添加一个 “文件夹” 排除项。选择你的项目文件夹。

在 macOS 上，你可以在终端中禁用 Gatekeeper。

1. 在终端中运行 sudo spctl developer-mode enable-terminal。
2. 打开 “系统设置” 应用，然后选择 “隐私与安全性” → “开发者工具”。
3. 确保你的终端已列出并启用。如果你使用的是第三方终端（如 iTerm 或 Ghostty），请将其添加到列表中。
4. 重启你的终端。

如果你或你的雇主在系统上配置了任何其他杀毒解决方案，你应该检查这些产品的相关设置。

2. 更新 Next.js 并使用 Turbopack

确保你正在使用最新版本的 Next.js。每个新版本通常都包含性能改进。

Turbopack 现在是 Next.js 开发的默认打包工具，并且比 webpack 提供了显著的性能改进。

npm install next@latest
npm run dev  # Turbopack is used by default

如果你需要使用 Webpack 而不是 Turbopack，可以选择启用：

npm run dev --webpack

了解更多关于 Turbopack 的信息。请参阅我们的升级指南和 codemods 以获取更多信息。

3. 检查你的导入

你导入代码的方式会极大地影响编译和打包时间。了解更多关于优化包打包的信息，并探索 Dependency Cruiser 或 Madge 等工具。

图标库

像 @material-ui/icons、@phosphor-icons/react 或 react-icons 这样的库可能会导入数千个图标，即使你只使用了其中几个。尝试只导入你需要的图标：

// Instead of this:
import { TriangleIcon } from "@phosphor-icons/react";

// Do this:
import { TriangleIcon } from "@phosphor-icons/react/dist/csr/Triangle";

你通常可以在你使用的图标库的文档中找到要使用的导入模式。这个示例遵循 @phosphor-icons/react 的建议。

像 react-icons 这样的库包含许多不同的图标集。选择一个集合并坚持使用该集合。

例如，如果你的应用程序使用 react-icons 并导入了所有这些：

• pi (Phosphor Icons)
• md (Material Design Icons)
• tb (tabler-icons)
• cg (cssgg)

它们总共将是数万个模块，即使你只从每个模块中使用了单个导入，编译器也必须处理它们。

桶文件

“桶文件”是指从其他文件导出许多项的文件。它们会减慢构建速度，因为编译器必须解析它们以通过导入查找模块作用域中是否存在副作用。

尽可能直接从特定文件导入。了解更多关于桶文件的信息以及 Next.js 中的内置优化。

优化包导入

Next.js 可以自动优化某些包的导入。如果你正在使用的包利用了桶文件，请将它们添加到你的 next.config.js 中：

module.exports = {
    experimental: {
        optimizePackageImports: ["package-name"],
    },
};

Turbopack 自动分析和优化导入。它不需要此配置。

4. 检查你的 Tailwind CSS 设置

如果你正在使用 Tailwind CSS，请确保它已正确设置。

一个常见的错误是配置 content 数组的方式包含了 node_modules 或其他不应被扫描的大量文件目录。

Tailwind CSS 3.4.8 或更新版本会警告你可能减慢构建速度的设置。

1. 在你的 tailwind.config.js 中，明确指定要扫描的文件：

   Copy

   jsx

   module.exports = {
       content: [
           "./src/**/*.{js,ts,jsx,tsx}", // Good
           // This might be too broad
           // It will match `packages/**/node_modules` too
           // '../../packages/**/*.{js,ts,jsx,tsx}',
       ],
   };

2. 避免扫描不必要的文件：

   Copy

   jsx

   module.exports = {
       content: [
           // Better - only scans the 'src' folder
           "../../packages/ui/src/**/*.{js,ts,jsx,tsx}",
       ],
   };

5. 检查自定义 webpack 设置

如果你添加了自定义 webpack 设置，它们可能会减慢编译速度。

考虑你是否真的需要它们用于本地开发。你可以选择只为生产构建包含某些工具，或者探索使用默认的 Turbopack 打包工具并配置 loaders。

6. 优化内存使用

如果你的应用程序非常大，它可能需要更多内存。

了解更多关于优化内存使用的信息。

7. 服务端组件和数据获取

对服务端组件的更改会导致整个页面在本地重新渲染以显示新更改，这包括为组件获取新数据。

实验性的 serverComponentsHmrCache 选项允许你在本地开发中，跨热模块替换 (HMR) 刷新时缓存服务端组件中的 fetch 响应。这可以带来更快的响应并降低计费 API 调用的成本。

了解更多关于此实验性选项的信息。

8. 优先考虑本地开发而非 Docker

如果你在 Mac 或 Windows 上使用 Docker 进行开发，你可能会遇到比在本地运行 Next.js 慢得多的性能。

Docker 在 Mac 和 Windows 上的文件系统访问可能导致热模块替换 (HMR) 耗时数秒甚至数分钟，而相同的应用程序在本地开发时可以实现快速 HMR。

这种性能差异是由于 Docker 在 Linux 环境之外处理文件系统操作的方式造成的。为了获得最佳开发体验：

• 在开发过程中使用本地开发（npm run dev 或 pnpm dev），而不是 Docker
• 将 Docker 保留用于生产部署和测试生产构建
• 如果你必须使用 Docker 进行开发，请考虑在 Linux 机器或虚拟机上使用 Docker

了解更多关于 Docker 生产用途部署的信息。

问题排查工具

详细的 fetch 日志

在你的 next.config.js 文件中使用 logging.fetches 选项，以查看开发过程中发生的更详细信息：

module.exports = {
    logging: {
        fetches: {
            fullUrl: true,
        },
    },
};

了解更多关于 fetch 日志的信息。

Turbopack 追踪

Turbopack 追踪是一种工具，可以帮助你了解应用程序在本地开发期间的性能。它提供了关于每个模块编译所需时间以及它们之间关联的详细信息。

1. 确保你已安装最新版本的 Next.js。

2. 生成一个 Turbopack 追踪文件：

   Copy

   bash

   NEXT_TURBOPACK_TRACING=1 npm run dev

3. 在你的应用程序中导航或修改文件以重现问题。

4. 停止 Next.js 开发服务器。

5. 一个名为 trace-turbopack 的文件将在 .next/dev 文件夹中可用。

6. 你可以使用 npx next internal trace [path-to-file] 解析该文件：

   Copy

   bash

   npx next internal trace .next/dev/trace-turbopack

   在 trace 不可用的版本中，该命令名为 turbo-trace-server：

   Copy

   bash

   npx next internal turbo-trace-server .next/dev/trace-turbopack

7. 一旦追踪服务器运行，你可以在 https://trace.nextjs.org/ 查看追踪。

8. 默认情况下，追踪查看器会聚合时间，为了查看各个时间点，你可以在查看器右上角将“按顺序聚合”切换为“按顺序跨度”。

须知：追踪文件位于开发服务器目录中，默认是 .next/dev。这可以通过 Next 配置文件中的 isolatedDevBuild 标志来控制。

仍然有问题？

分享在 Turbopack 追踪 部分生成的追踪文件，并将其分享到 GitHub Discussions 或 Discord。