Skip to main content

output

在构建过程中，Next.js 将自动跟踪每个页面及其依赖，以确定部署应用的生产版本所需的所有文件。

¥During a build, Next.js will automatically trace each page and its dependencies to determine all of the files that are needed for deploying a production version of your application.

此功能有助于大幅减少部署规模。以前，使用 Docker 进行部署时，你需要安装软件包 dependencies 中的所有文件才能运行 next start。从 Next.js 12 开始，你可以利用 .next/ 目录中的输出文件跟踪来仅包含必要的文件。

¥This feature helps reduce the size of deployments drastically. Previously, when deploying with Docker you would need to have all files from your package's dependencies installed to run next start. Starting with Next.js 12, you can leverage Output File Tracing in the .next/ directory to only include the necessary files.

此外，这消除了对已弃用的 serverless 目标的需要，该目标可能会导致各种问题并产生不必要的重复。

¥Furthermore, this removes the need for the deprecated serverless target which can cause various issues and also creates unnecessary duplication.

怎么运行的​

¥How it Works

在 next build 期间，Next.js 将使用 @vercel/nft 静态分析 import、require 和 fs 的使用情况，以确定页面可能加载的所有文件。

¥During next build, Next.js will use @vercel/nft to statically analyze import, require, and fs usage to determine all files that a page might load.

Next.js 的生产服务器也会在 .next/next-server.js.nft.json 处跟踪其所需的文件和输出，这些文件和输出可在生产中利用。

¥Next.js' production server is also traced for its needed files and output at .next/next-server.js.nft.json which can be leveraged in production.

要利用发送到 .next 输出目录的 .nft.json 文件，你可以读取每个跟踪中与 .nft.json 文件相关的文件列表，然后将它们复制到你的部署位置。

¥To leverage the .nft.json files emitted to the .next output directory, you can read the list of files in each trace that are relative to the .nft.json file and then copy them to your deployment location.

自动复制跟踪文件​

¥Automatically Copying Traced Files

Next.js 可以自动创建 standalone 文件夹，仅复制生产部署所需的文件，包括 node_modules 中的选定文件。

¥Next.js can automatically create a standalone folder that copies only the necessary files for a production deployment including select files in node_modules.

要利用此自动复制功能，你可以在 next.config.js 中启用它：

¥To leverage this automatic copying you can enable it in your next.config.js:

module.exports = {
  output: 'standalone',
}

这将在 .next/standalone 创建一个文件夹，然后可以单独部署该文件夹，而无需安装 node_modules。

¥This will create a folder at .next/standalone which can then be deployed on its own without installing node_modules.

此外，还输出最小的 server.js 文件，可以使用它来代替 next start。默认情况下，这个最小的服务器不会复制 public 或 .next/static 文件夹，因为理想情况下这些文件夹应该由 CDN 处理，尽管这些文件夹可以手动复制到 standalone/public 和 standalone/.next/static 文件夹，之后 server.js 文件将自动提供这些文件夹。

¥Additionally, a minimal server.js file is also output which can be used instead of next start. This minimal server does not copy the public or .next/static folders by default as these should ideally be handled by a CDN instead, although these folders can be copied to the standalone/public and standalone/.next/static folders manually, after which server.js file will serve these automatically.

要手动复制这些，你可以在 next build 之后使用 cp 命令行工具：

¥To copy these manually, you can use the cp command-line tool after you next build:

cp -r public .next/standalone/ && cp -r .next/static .next/standalone/.next/

要在本地启动最小 server.js 文件，请运行以下命令：

¥To start your minimal server.js file locally, run the following command:

node .next/standalone/server.js

很高兴知道：

¥Good to know:

  • 如果你的项目需要监听特定端口或主机名，你可以在运行 server.js 之前定义 PORT 或 HOSTNAME 环境变量。例如，运行 PORT=8080 HOSTNAME=0.0.0.0 node server.js 以启动 http://0.0.0.0:8080 上的服务器。

    ¥If your project needs to listen to a specific port or hostname, you can define PORT or HOSTNAME environment variables before running server.js. For example, run PORT=8080 HOSTNAME=0.0.0.0 node server.js to start the server on http://0.0.0.0:8080.

注意事项​

¥Caveats

  • 在 monorepo 设置中进行跟踪时，默认情况下使用项目目录进行跟踪。对于 next build packages/web-app，packages/web-app 将是跟踪根目录，并且不会包含该文件夹之外的任何文件。要包含此文件夹之外的文件，你可以在 next.config.js 中设置 outputFileTracingRoot。

    ¥While tracing in monorepo setups, the project directory is used for tracing by default. For next build packages/web-app, packages/web-app would be the tracing root and any files outside of that folder will not be included. To include files outside of this folder you can set outputFileTracingRoot in your next.config.js.

module.exports = {
  // this includes files from the monorepo base two directories up
  outputFileTracingRoot: path.join(__dirname, '../../'),
}

  • 在某些情况下，Next.js 可能无法包含所需的文件，或者可能错误地包含未使用的文件。在这些情况下，你可以在 next.config.js 中分别利用 outputFileTracingExcludes 和 outputFileTracingIncludes。每个配置接受一个带有 迷你匹配球 的对象作为匹配特定页面的键，以及一个数组的值，该数组的值相对于项目的根目录，以便在跟踪中包含或排除。

    ¥There are some cases in which Next.js might fail to include required files, or might incorrectly include unused files. In those cases, you can leverage outputFileTracingExcludes and outputFileTracingIncludes respectively in next.config.js. Each config accepts an object with minimatch globs for the key to match specific pages and a value of an array with globs relative to the project's root to either include or exclude in the trace.

module.exports = {
  outputFileTracingExcludes: {
    '/api/hello': ['./un-necessary-folder/**/*'],
  },
  outputFileTracingIncludes: {
    '/api/another': ['./necessary-folder/**/*'],
    '/api/login/\\[\\[\\.\\.\\.slug\\]\\]': [
      './node_modules/aws-crt/dist/bin/**/*',
    ],
  },
}

注意：outputFileTracingIncludes/outputFileTracingExcludes 的键是 glob，因此需要转义特殊字符。

¥Note: The key of outputFileTracingIncludes/outputFileTracingExcludes is a glob, so special characters need to be escaped.

  • 目前，Next.js 不会对发出的 .nft.json 文件执行任何操作。这些文件必须由你的部署平台（例如 Vercel）读取，才能创建最小部署。在未来的版本中，计划使用一个新命令来利用这些 .nft.json 文件。

    ¥Currently, Next.js does not do anything with the emitted .nft.json files. The files must be read by your deployment platform, for example Vercel, to create a minimal deployment. In a future release, a new command is planned to utilize these .nft.json files.

实验 turbotrace​

¥Experimental turbotrace

跟踪依赖可能会很慢，因为它需要非常复杂的计算和分析。我们在 Rust 中创建了 turbotrace，作为 JavaScript 实现的更快、更智能的替代方案。

¥Tracing dependencies can be slow because it requires very complex computations and analysis. We created turbotrace in Rust as a faster and smarter alternative to the JavaScript implementation.

要启用它，你可以将以下配置添加到 next.config.js：

¥To enable it, you can add the following configuration to your next.config.js:

module.exports = {
  experimental: {
    turbotrace: {
      // control the log level of the turbotrace, default is `error`
      logLevel?:
      | 'bug'
      | 'fatal'
      | 'error'
      | 'warning'
      | 'hint'
      | 'note'
      | 'suggestions'
      | 'info',
      // control if the log of turbotrace should contain the details of the analysis, default is `false`
      logDetail?: boolean
      // show all log messages without limit
      // turbotrace only show 1 log message for each categories by default
      logAll?: boolean
      // control the context directory of the turbotrace
      // files outside of the context directory will not be traced
      // set the `outputFileTracingRoot` has the same effect
      // if the `outputFileTracingRoot` and this option are both set, the `experimental.turbotrace.contextDirectory` will be used
      contextDirectory?: string
      // if there is `process.cwd()` expression in your code, you can set this option to tell `turbotrace` the value of `process.cwd()` while tracing.
      // for example the require(process.cwd() + '/package.json') will be traced as require('/path/to/cwd/package.json')
      processCwd?: string
      // control the maximum memory usage of the `turbotrace`, in `MB`, default is `6000`.
      memoryLimit?: number
    },
  },
}