如何优化你的本地开发环境

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

本地开发与生产环境

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

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

提升本地开发性能

1. 检查你计算机的杀毒软件

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

在 Windows 上，你可以将项目添加到 Microsoft Defender 杀毒软件排除列表。

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

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

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

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

2. 更新 Next.js 并使用 Turbopack

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

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

npm install next@latest
npm run dev  # 默认使用 Turbopack

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

npm run dev --webpack

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

3. 检查你的导入

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

图标库

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

// 不要这样做：
import { TriangleIcon } from '@phosphor-icons/react'
 
// 这样做：
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）

它们加起来将是数万个模块，编译器必须处理这些模块，即使你只使用每个模块中的单个导入。

Barrel 文件

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

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

优化包导入

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

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

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

4. 检查你的 Tailwind CSS 设置

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

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

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

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

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

避免扫描不必要的文件：

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

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

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 跟踪是一个工具，可帮助你了解应用程序在本地开发期间的性能。它提供有关每个模块编译所需时间以及它们如何相关的详细信息。

确保你已安装最新版本的 Next.js。
生成 Turbopack 跟踪文件：
```
NEXT_TURBOPACK_TRACING=1 npm run dev
```
在应用程序中导航或对文件进行编辑以重现问题。
停止 Next.js 开发服务器。
一个名为 trace-turbopack 的文件将在 .next/dev 文件夹中可用。
你可以使用 npx next internal trace [path-to-file] 解释该文件：
```
npx next internal trace .next/dev/trace-turbopack
```
在 trace 不可用的版本上，该命令被命名为 turbo-trace-server：
```
npx next internal turbo-trace-server .next/dev/trace-turbopack
```
跟踪服务器运行后，你可以在 https://trace.nextjs.org/ 查看跟踪。
默认情况下，跟踪查看器将聚合时间，为了查看每个单独的时间，你可以在查看器的右上角从"按顺序聚合"切换到"按顺序显示跨度"。

值得注意的是：跟踪文件放置在开发服务器目录下，默认为 .next/dev。这可以使用 Next 配置文件中的 isolatedDevBuild 标志来控制。

仍然遇到问题？

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