如何优化本地开发环境
了解如何使用 Next.js 优化本地开发环境。
Next.js 旨在提供出色的开发者体验。随着应用规模的增长,你可能会注意到本地开发时编译时间变慢。本指南将帮助你识别并修复常见的编译时性能问题。
本地开发与生产环境对比#
使用 next dev 的开发过程与 next build 和 next start 不同。
next dev 会在你打开或导航到应用中的路由时编译它们。这使你无需等待应用中的每个路由都编译完成即可启动开发服务器,既更快又占用更少的内存。运行生产构建会应用其他优化,例如压缩文件和创建内容哈希,这些在本地开发中并不需要。
系统配置#
1. 检查电脑的杀毒软件#
杀毒软件可能会减慢文件访问速度。虽然这在 Windows 机器上更常见,但对于任何安装了杀毒工具的系统来说都可能是个问题。
在 Windows 上, 你可以将项目添加到 Microsoft Defender 防病毒排除列表。
- 打开 "Windows 安全中心" 应用,然后选择 "病毒和威胁防护" → "管理设置" → "添加或删除排除项"。
- 添加 "文件夹" 排除项。选择你的项目文件夹。
或者,你可以启用并使用 Dev Drive,它使用 Microsoft Defender 的"性能模式"。
在 macOS 上, 你可以在终端中禁用 Gatekeeper。
- 在终端中运行
sudo spctl developer-mode enable-terminal。 - 打开 "系统设置" 应用,然后选择 "隐私与安全性" → "开发者工具"。
- 确保你的终端在列表中并已启用。如果你使用第三方终端(如 iTerm 或 Ghostty),请将其添加到列表中。
- 重启终端。
如果你或你的雇主在系统中配置了其他杀毒解决方案,你应该检查这些产品的相关设置。
2. 避免常见的 Docker 陷阱#
如果你在 Mac 或 Windows 上使用 Docker 进行开发,与不使用 Docker 运行 Next.js 相比,你可能会遇到明显更慢的性能。
这在生产环境中或 Docker 原生运行在 Linux 上时通常不是问题,因为项目文件不会跨越 Docker Desktop 的主机到虚拟机的文件共享层。
当项目文件存储在 macOS 或 Windows 主机上,并通过 Docker Desktop 或类似工具挂载到容器中时,主机到虚拟机的文件共享层可能会延迟或无法传播文件系统事件。这可能导致 Fast Refresh 耗时数秒甚至数分钟,而同一应用在不使用 Docker 的主机上开发时更新很快。
为了获得最佳开发体验:
- 开发时不使用 Docker 运行 Next.js(
npm run dev或pnpm dev)。 - 将 Docker 保留用于生产部署和测试生产构建。
- 如果必须使用 Docker 进行开发,请考虑在 Linux 机器或手动配置的虚拟机上原生运行 Docker。如果使用手动配置的虚拟机,请将源代码移入虚拟机,不要从主机共享。
- 如果你使用 Docker Desktop,请评估使用同步文件共享。同步文件共享与直接在主机上运行 Next.js 相比仍会增加延迟,但可以提高文件监听的可靠性,而无需诉诸轮询。
- 避免使用
next.config.js中的watchOptions.pollIntervalMs来解决 Fast Refresh 问题。仅将其作为最后手段。轮询会显著增加延迟,并可能大幅增加 CPU 和 I/O 使用率。
了解更多关于 Docker 部署的信息,以供生产使用。
3.(Windows)使用 Dev Drive 或 WSL 2#
Windows 11 的 Dev Drive 功能使用替代文件系统来提升常见开发工作流的性能。Microsoft 提供了一份指南说明如何配置它。
或者,Windows 提供了一种使用 Windows Subsystem for Linux 设置 Linux 虚拟机的简单方法。使用 WSL 2 可能会获得更好的性能。
使用 WSL 2 时,请将项目目录存储在虚拟机的文件系统内(例如 /home/$USER/project),而不是 Windows 驱动器上(例如 C:\ 或 /mnt/c)。如果不这样做,你将遇到更差的性能,并且文件更新可能无法在开发中正确反映。
提升应用开发性能#
1. 更新 Next.js 并使用 Turbopack#
确保你使用的是最新版本的 Next.js。每个新版本通常都包含性能改进。
Turbopack 现在是 Next.js 开发的默认打包工具,与 webpack 相比提供了显著的性能提升。
pnpm add next@latest
pnpm dev # 默认使用 Turbopacknpm install next@latest
npm run dev # 默认使用 Turbopackyarn add next@latest
yarn dev # 默认使用 Turbopackbun add next@latest
bun dev # 默认使用 Turbopack如果你需要使用 Webpack 而不是 Turbopack,可以选择启用:
pnpm dev --webpacknpm run dev -- --webpackyarn dev --webpackbun run dev --webpack了解更多关于 Turbopack 的信息。请参阅我们的升级指南和 codemods 了解更多信息。
2. 检查你的导入#
导入代码的方式会极大地影响编译和打包时间。了解有关优化包打包的更多信息,并探索 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 图标)md(Material Design 图标)tb(tabler-icons)cg(cssgg)
加在一起,它们将是编译器必须处理的数万个模块,即使你每个只使用一次导入。
Barrel 文件#
“Barrel 文件”是指从其他文件导出许多内容的文件。它们会减慢构建速度,因为编译器必须解析它们,以查找通过使用导入是否在模块作用域中存在副作用。
尽可能尝试从特定文件直接导入。了解更多关于 Barrel 文件以及 Next.js 中的内置优化。
优化包导入#
Next.js 可以自动优化某些包的导入。如果你使用利用 Barrel 文件的包,请将它们添加到 next.config.js 中:
module.exports = {
experimental: {
optimizePackageImports: ['package-name'],
},
}Turbopack 会自动分析并优化导入。它不需要此配置。
3. 检查你的 Tailwind CSS 设置#
如果你使用 Tailwind CSS,请确保其设置正确。
一个常见的错误是以一种包含 node_modules 或其他不应被扫描的大型文件目录的方式配置 content 数组。
Tailwind CSS 3.4.8 或更高版本会就可能减慢构建的设置向你发出警告。
- 在
tailwind.config.js中,明确指定要扫描的文件:
```jsx module.exports = {
content: [
'./src/**/*.{js,ts,jsx,tsx}', // 合适
// 这可能太宽泛
// 它也会匹配 `packages/**/node_modules`
// '../../packages/**/*.{js,ts,jsx,tsx}',
],} ```
- 避免扫描不必要的文件:
```jsx module.exports = {
content: [
// 更好——只扫描 'src' 文件夹
'../../packages/ui/src/**/*.{js,ts,jsx,tsx}',
],} ```
4. 检查自定义 webpack 设置#
如果你添加了自定义 webpack 设置,它们可能会减慢编译速度。
考虑本地开发是否真的需要它们。你可以选择仅在构建生产版本时包含某些工具,或者探索使用默认的 Turbopack 打包工具并配置 loaders。
5. 优化内存使用#
如果你的应用非常大,它可能需要更多内存。
6. Server Components 与数据获取#
对 Server Components 的更改会导致整个页面在本地重新渲染以显示新的更改,其中包括为该组件获取新数据。
实验性的 serverComponentsHmrCache 选项允许你在本地开发中跨热模块替换(HMR)刷新缓存 Server Components 中的 fetch 响应。这可以加快响应速度并降低计费 API 调用的成本。
查找问题的工具#
详细的 fetch 日志#
使用 next.config.js 文件中的 logging.fetches 选项,查看有关开发过程中发生情况的更详细信息:
module.exports = {
logging: {
fetches: {
fullUrl: true,
},
},
}Turbopack 追踪#
Turbopack 追踪是一个帮助你了解应用在本地开发期间性能的工具。它提供有关每个模块编译耗时及其相互关系的详细信息。
- 确保你已安装最新版本的 Next.js。
- 生成 Turbopack 追踪文件:
``bash package="pnpm" pnpm dev --internal-trace ``
``bash package="npm" npm run dev -- --internal-trace ``
``bash package="yarn" yarn dev --internal-trace ``
``bash package="bun" bun dev --internal-trace ``
- 在应用中导航或修改文件以重现问题。
- 停止 Next.js 开发服务器。
.next-profiles文件夹中将生成一个名为trace-turbopack.bin的文件。- 你可以使用
npx next internal trace [path-to-file]解读该文件:
``bash npx next internal trace .next-profiles/trace-turbopack.bin ``
在 trace 不可用的版本中,该命令名为 turbo-trace-server:
``bash npx next internal turbo-trace-server .next-profiles/trace-turbopack.bin ``
- 追踪服务器运行后,你可以在 https://trace.nextjs.org/ 查看追踪。
- 默认情况下,追踪查看器会聚合时间;若要查看每个单独的时间,你可以在查看器右上角从 "Aggregated in order"(按聚合排序)切换到 "Spans in order"(按 Span 排序)。
小知识:追踪文件位于项目根目录的
.next-profiles目录中。
仍然遇到问题?#
分享在 Turbopack 追踪部分生成的追踪文件,并将其发布到 GitHub Discussions 或 Discord。