Menu

How to optimize your local development environment

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

本地开发与生产环境的区别

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

next dev 会在你打开或导航到路由时编译应用程序中的路由。这使你能够启动开发服务器而无需等待应用程序中的每个路由编译完成，这既快速又节省内存。运行生产构建会应用其他优化，如压缩文件和创建内容哈希，这些在本地开发中并不需要。

提升本地开发性能

1. 检查你的电脑杀毒软件

杀毒软件可能会减慢文件访问速度。

尝试将你的项目文件夹添加到杀毒软件的排除列表中。虽然这在 Windows 机器上更为常见，但我们建议对任何安装了杀毒工具的系统都这样做。

2. 更新 Next.js 并启用 Turbopack

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

Turbopack 是集成到 Next.js 中的新打包工具，可以提高本地性能。

npm install next@latest
npm run dev --turbopack

了解更多关于 Turbopack 的信息。查看我们的升级指南和代码修改工具获取更多信息。

3. 检查你的导入

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

图标库

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

// 不要这样做：
import { Icon1, Icon2 } from 'react-icons/md'
 
// 应该这样做：
import Icon1 from 'react-icons/md/Icon1'
import Icon2 from 'react-icons/md/Icon2'

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

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

  • pi（Phosphor Icons）
  • md（Material Design Icons）
  • tb（tabler-icons）
  • cg（cssgg）

它们加起来将有数万个模块需要编译器处理，即使你只从每个集合中导入一个图标。

聚合文件（Barrel files）

"聚合文件"是从其他文件导出多个项目的文件。它们可能会减慢构建速度，因为编译器必须解析它们，以查找使用导入时模块作用域中是否有副作用。

尽可能直接从特定文件导入。了解更多关于聚合文件和 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 中，具体指定要扫描的文件：

    module.exports = {
  content: [
    './src/**/*.{js,ts,jsx,tsx}', // 好的做法
    // 这可能范围太广
    // 它也会匹配 `packages/**/node_modules`
    // '../../packages/**/*.{js,ts,jsx,tsx}',
  ],
}

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

    module.exports = {
  content: [
    // 更好 - 只扫描 'src' 文件夹
    '../../packages/ui/src/**/*.{js,ts,jsx,tsx}',
  ],
}

5. 检查自定义 webpack 设置

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

考虑你是否真的需要它们用于本地开发。你可以选择只在生产构建中包含某些工具，或考虑转移到 Turbopack 并使用加载器。

6. 优化内存使用

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

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

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

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

实验性的 serverComponentsHmrCache 选项允许你在本地开发中缓存服务器组件中的 fetch 响应，使其在热模块替换（HMR）刷新时可用。这会带来更快的响应速度并减少计费 API 调用的成本。

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

查找问题的工具

详细获取日志

使用此命令查看开发过程中更详细的信息：

next dev --verbose

Turbopack 跟踪

Turbopack 跟踪是一个帮助你了解本地开发期间应用程序性能的工具。 它提供每个模块编译所需时间及其相互关系的详细信息。

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

  2. 生成 Turbopack 跟踪文件：

    NEXT_TURBOPACK_TRACING=1 npm run dev

  3. 在应用程序中导航或编辑文件以重现问题。

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

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

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

    next internal trace .next/trace-turbopack

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

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

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

  8. 默认情况下，跟踪查看器会聚合时间，要查看每个单独的时间，你可以在查看器右上角将"Aggregated in order"切换为"Spans in order"。

仍有问题？

分享在 Turbopack 跟踪 部分生成的跟踪文件，并在 GitHub Discussions 或 Discord 上分享。