跳到内容
App Router指南开发环境

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

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

本地开发与生产

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

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

提升本地开发性能

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

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

在 Windows 上，您可以将项目添加到 Microsoft Defender 防病毒排除列表 中。

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

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

  1. 在您的终端中运行 sudo spctl developer-mode enable-terminal。
  2. 打开 **"系统设置"** 应用程序，然后选择 **"隐私与安全性"** → **"开发者工具"**。
  3. 确保您的终端已列出并已启用。如果您正在使用第三方终端（如 iTerm 或 Ghostty），请将其添加到列表中。
  4. 重新启动您的终端。
Screenshot of macOS System Settings showing the Privacy & Security pane
Screenshot of macOS System Settings showing the Developer Tools options

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

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 中，请明确指定要扫描的文件。

    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. 避免扫描不必要的文件。

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

5. 检查自定义 webpack 设置

如果您添加了自定义 webpack 设置，它们可能会降低编译速度。

考虑您是否真的需要它们用于本地开发。您可以选择仅将某些工具包含在生产构建中，或者探索使用默认的 Turbopack 打包器并配置 加载器。

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 追踪文件

    NEXT_TURBOPACK_TRACING=1 npm run dev

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

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

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

  6. 您可以使用 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

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

  8. 默认情况下，追踪查看器将聚合计时，为了查看每个单独的计时，您可以在查看器右上方从“按顺序聚合”切换到“按顺序跨度”。

须知：追踪文件放置在开发服务器目录中，默认为 .next/dev。这可以通过您的 Next 配置文件中的 isolatedDevBuild 标志进行控制。

仍然有问题？

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