本地开发

¥Local Development

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

¥Next.js is designed to provide a great developer experience. As your application grows, you might notice slower compilation times during local development. This guide will help you identify and fix common compile-time performance issues.

本地开发 vs. 生产环境

¥Local dev vs. production

next dev 的开发流程与 next build 和 next start 不同。

¥The development process with next dev is different than next build and next start.

next dev 会在你打开或导航到应用中的路由时对其进行编译。这使你无需等待应用中每个路由都编译完毕即可启动开发服务器，从而提高速度并减少内存占用。运行生产构建会应用其他优化，例如最小化文件和创建内容哈希，这些优化对于本地开发来说并非必需。

¥next dev compiles routes in your application as you open or navigate to them. This enables you to start the dev server without waiting for every route in your application to compile, which is both faster and uses less memory. Running a production build applies other optimizations, like minifying files and creating content hashes, which are not needed for local development.

提升本地开发性能

¥Improving local dev performance

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

¥ Check your computer's antivirus

防病毒软件会降低文件访问速度。

¥Antivirus software can slow down file access.

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

¥Try adding your project folder to the antivirus exclusion list. While this is more common on Windows machines, we recommend this for any system with an antivirus tool installed.

2. 更新 Next.js 并启用 Turbopack

¥ Update Next.js and enable Turbopack

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

¥Make sure you're using the latest version of Next.js. Each new version often includes performance improvements.

Turbopack 是集成到 Next.js 中的一款新打包器，可以提升本地性能。

¥Turbopack is a new bundler integrated into Next.js that can improve local performance.

npm install next@latest
npm run dev --turbopack

了解更多关于 Turbopack 的信息。有关更多信息，请参阅我们的 升级指南 和 codemods。

¥Learn more about Turbopack. See our upgrade guides and codemods for more information.

3. 检查你的导入

¥ Check your imports

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

¥The way you import code can greatly affect compilation and bundling time. Learn more about optimizing package bundling and explore tools like Dependency Cruiser or Madge.

图标库

¥Icon libraries

像 @material-ui/icons 或 react-icons 这样的库可以导入数千个图标，即使你只使用几个。尽量只导入你需要的图标：

¥Libraries like @material-ui/icons or react-icons can import thousands of icons, even if you only use a few. Try to import only the icons you need:

// Instead of this:
import { Icon1, Icon2 } from 'react-icons/md'

// Do this:
import Icon1 from 'react-icons/md/Icon1'
import Icon2 from 'react-icons/md/Icon2'

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

¥Libraries like react-icons includes many different icon sets. Choose one set and stick with that set.

例如，如果你的应用使用 react-icons 并导入了以下所有内容：

¥For example, if your application uses react-icons and imports all of these:

• pi(Phosphor Icons)

• md(Material Design)图标)

  ¥md (Material Design Icons)

• tb(tabler-icons)

• cg(cssgg)

即使每个模块只导入一次，编译器也需要处理成千上万个模块。

¥Combined they will be tens of thousands of modules that the compiler has to handle, even if you only use a single import from each.

Barrel 文件

¥Barrel files

"Barrel 文件" 是从其他文件导出许多项目的文件。它们可能会降低构建速度，因为编译器必须解析它们，以确定导入操作是否会在模块范围内产生副作用。

¥"Barrel files" are files that export many items from other files. They can slow down builds because the compiler has to parse them to find if there are side-effects in the module scope by using the import.

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

¥Try to import directly from specific files when possible. Learn more about barrel files and the built-in optimizations in Next.js.

优化包导入

¥Optimize package imports

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

¥Next.js can automatically optimize imports for certain packages. If you are using packages that utilize barrel files, add them to your next.config.js:

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

4. 检查你的 Tailwind CSS 设置

¥ Check your Tailwind CSS setup

如果你使用的是 Tailwind CSS，请确保其设置正确。

¥If you're using Tailwind CSS, make sure it's set up correctly.

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

¥A common mistake is configuring your content array in a way which includes node_modules or other large directories of files that should not be scanned.

Tailwind CSS 3.4.8 或更新版本会警告你有关可能降低构建速度的设置。

¥Tailwind CSS version 3.4.8 or newer will warn you about settings that might slow down your build.

1. 在你的 tailwind.config.js 中，请具体说明要扫描哪些文件：

   ¥In your tailwind.config.js, be specific about which files to scan:

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

   ¥Avoid scanning unnecessary files:

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

5. 检查自定义 webpack 设置

¥ Check custom webpack settings

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

¥If you've added custom webpack settings, they might be slowing down compilation.

考虑你是否真的需要它们进行本地开发。你可以选择仅在生产版本中包含某些工具，或者尝试迁移到 Turbopack 并使用 loaders。

¥Consider if you really need them for local development. You can optionally only include certain tools for production builds, or explore moving to Turbopack and using loaders.

6. 优化内存使用

¥ Optimize memory usage

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

¥If your app is very large, it might need more memory.

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

¥Learn more about optimizing memory usage.

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

¥ Server Components and data fetching

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

¥Changes to Server Components cause the entire page to re-render locally in order to show the new changes, which includes fetching new data for the component.

实验性的 serverComponentsHmrCache 选项允许你在本地开发中的热模块替换 (HMR) 刷新中缓存服务器组件中的 fetch 响应。这可以加快响应速度并降低计费 API 调用的成本。

¥The experimental serverComponentsHmrCache option allows you to cache fetch responses in Server Components across Hot Module Replacement (HMR) refreshes in local development. This results in faster responses and reduced costs for billed API calls.

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

¥Learn more about the experimental option.

查找问题的工具

¥Tools for finding problems

详细的 fetch 日志记录

¥Detailed fetch logging

使用此命令查看有关开发过程中发生情况的更多详细信息：

¥Use this command to see more detailed information about what's happening during development:

next dev --verbose

仍然有问题？

¥Still having problems?

如果你已尝试所有方法但仍有问题：

¥If you've tried everything and still have issues:

1. 创建一个显示问题的简单应用版本。

   ¥Create a simple version of your app that shows the problem.

2. 生成一个特殊文件来展示正在发生的事情：

   ¥Generate a special file that shows what's happening:

   NEXT_CPU_PROF=1 npm run dev

3. 将此文件（位于项目主文件夹中）和 .next/trace 文件作为新问题分享到 GitHub。

   ¥Share this file (found in your project's main folder) and the .next/trace file on GitHub as a new issue.