Next.js 中文网

主题

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:

这将在 .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:

bash
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:

bash
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.

  • 在某些情况下，Next.js 可能无法包含所需的文件，或者可能错误地包含未使用的文件。在这些情况下，你可以在 next.config.js 中分别利用 outputFileTracingExcludes 和 outputFileTracingIncludes。每个选项都接受一个对象，该对象的键是路由 glob 模式（与路由路径 /api/hello 匹配，并使用 picomatch），其值是从项目根目录解析的 glob 模式，用于指定要在跟踪中包含或排除的文件。

    ¥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 option accepts an object whose keys are route globs (matched with picomatch against the route path, e.g. /api/hello) and whose values are glob patterns resolved from the project root that specify files to include or exclude in the trace.

需要了解：在 monorepo 中，project root 指的是 Next.js 项目根目录（包含 next.config.js 的文件夹，例如 packages/web-app），不一定是 monorepo 根目录。

¥Good to know: In a monorepo, project root refers to the Next.js project root (the folder containing next.config.js, e.g., packages/web-app), not necessarily the monorepo root.

使用 src/ 目录不会改变你编写这些选项的方式：

¥Using a src/ directory does not change how you write these options:

  • 键仍然与路由路径匹配（'/api/hello'、'/products/[id]' 等）。

    ¥Keys still match the route path ('/api/hello', '/products/[id]', etc.).

  • 值可以引用 src/ 下的路径，因为它们是相对于项目根目录解析的。

    ¥Values can reference paths under src/ since they are resolved relative to the project root.

你还可以使用类似 '/*' 的全局键来定位所有路由：

¥You can also target all routes using a global key like '/*':

这些选项应用于服务器跟踪，不会影响不生成服务器跟踪文件的路由：

¥These options are applied to server traces and do not affect routes that do not produce a server trace file:

  • Edge Runtime 路由不受影响。

    ¥Edge Runtime routes are not affected.

  • 完全静态的页面不受影响。

    ¥Fully static pages are not affected.

在 monorepo 中或需要包含应用文件夹之外的文件时，请将 outputFileTracingRoot 与 includes 结合使用：

¥In monorepos or when you need to include files outside the app folder, combine outputFileTracingRoot with includes:

需要了解：

¥Good to know:

  • 为了跨平台兼容性，建议在模式中使用正斜杠 (/)。

    ¥Prefer forward slashes (/) in patterns for cross-platform compatibility.

  • 尽可能缩小模式范围，以避免过大的跟踪信息（避免在仓库根目录使用 **/*）。

    ¥Keep patterns as narrow as possible to avoid oversized traces (avoid **/* at the repo root).

原生/运行时资源的常用包含模式：

¥Common include patterns for native/runtime assets: