如何优化本地开发环境

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 等库包含多套图标集。建议选择一套并坚持使用。

例如，若应用同时导入以下图标集：

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 及以上版本会对可能拖慢构建的配置发出警告。

在 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}', ], }

5. 检查自定义 webpack 配置

自定义 webpack 设置可能降低编译速度。

评估这些配置是否真为本地开发所需。可考虑仅在生产构建中启用，或迁移至 Turbopack 并使用加载器。

6. 优化内存使用

大型应用可能需要更多内存。

了解内存优化技巧。

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

服务器组件的变更会导致本地整个页面重新渲染（包括重新获取组件数据）。

实验性选项 serverComponentsHmrCache 允许在本地开发的热模块替换 (HMR) 过程中缓存 fetch 响应，从而加速响应并减少计费 API 调用。

了解该实验性选项。

问题诊断工具

详细获取日志

在 next.config.js 中启用 logging.fetches 选项以查看开发期间的详细请求信息：

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

了解获取日志详情。

Turbopack 追踪分析

Turbopack 追踪工具可帮助理解本地开发期间的性能表现，提供各模块编译耗时及关联关系的详细信息。

确保安装最新版 Next.js
生成追踪文件：
NEXT_TURBOPACK_TRACING=1 npm run dev
在应用中导航或编辑文件以复现问题
停止 Next.js 开发服务器
在 .next 目录中找到 trace-turbopack 文件
使用以下命令解析文件：
next internal trace .next/trace-turbopack
若版本不支持 trace 命令，请使用旧版命令：
next internal turbo-trace-server .next/trace-turbopack
启动追踪服务器后，访问 https://trace.nextjs.org/ 查看结果
默认显示聚合时间，如需查看每个独立耗时，可在查看器右上角将"Aggregated in order"切换为"Spans in order"

问题仍未解决？

将在 Turbopack 追踪环节生成的追踪文件分享至 GitHub Discussions 或 Discord 社区。

On this page