NNext.js 中文网 GitHub

output

Next.js 会自动追踪每个页面所需的文件,以便轻松部署你的应用。在此了解其工作原理。

在构建期间,Next.js 会自动追踪每个页面及其依赖项,以确定部署应用生产版本所需的所有文件。

此功能有助于大幅减小部署体积。以前,使用 Docker 部署时,你需要安装包 dependencies 中的所有文件才能运行 next start。从 Next.js 12 开始,你可以利用 .next/ 目录中的 Output File Tracing(输出文件追踪),只包含必要的文件。

此外,这也消除了对已弃用的 serverless target 的需求,后者可能导致各种问题,并造成不必要的重复。

工作原理#

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

Next.js 的生产服务器也会被追踪其所需文件,并输出到 .next/next-server.js.nft.json,可在生产环境中使用。

要利用输出到 .next 目录的 .nft.json 文件,你可以读取每个追踪记录中相对于 .nft.json 文件的文件列表,然后将它们复制到你的部署位置。

Turbopack NFT 扩展#

Turbopack 的 .nft.json 文件包含 fileHashes 和 symlinks 扩展:

  • fileHashes 是一个与 files 长度和顺序相同的并行数组。例如,fileHashes[0] 是 files[0] 的哈希。使用者可以将该哈希用作内容标识符,以缓存或去重被追踪的资源。
  • symlinks 将同级 files 数组中的索引映射到其直接目标。当存在 symlinks 时,没有对应条目的文件可以视为普通文件或目录。

使用额外根目录的追踪记录还包含 additionalRoots 扩展:

  • additionalRoots 是一个有序的命名源根目录列表。每个根目录都有自己的 files、fileHashes 和 symlinks 列表。它的 path 相对于包含 .nft.json 文件的目录,并标识构建机器上的源位置。名称保证是有效的目录名。

自动复制被追踪的文件#

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

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

next.config.js
module.exports = {
  output: 'standalone',
}

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

在 Windows 上,创建目录符号链接可能需要提升的权限或开发者模式。如果 standalone 生成必须回退到 junction point,Windows 会存储绝对路径目标,该特定输出将不可重定位。

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

要手动复制这些文件,你可以在 next build 之后使用 cp 命令行工具:

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

要在本地启动你的最小 server.js 文件,请运行以下命令:

Terminal
node .next/standalone/server.js

小知识:

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

小知识:

  • next.config.js 在 next build 期间被读取,并被序列化到 server.js 输出文件中。
  • 如果你的项目需要监听特定的端口或主机名,你可以在运行 server.js 之前定义 PORT 或 HOSTNAME 环境变量。例如,运行 PORT=8080 HOSTNAME=0.0.0.0 node server.js 以在 http://0.0.0.0:8080 上启动服务器。

环境变量文件#

当 next build 加载 .env 或 .env.production 文件时,standalone 输出会在 .next/standalone 中包含其副本。在运行时,server.js 将这些副本作为默认值读取:服务器启动时设置的环境变量优先,任何未设置的变量都会回退到副本中的值。

构建加载的其他文件(如 .env.local 和 .env.production.local)不会被复制。它们的值仍然适用于构建时的工作,例如预渲染页面和内联的 NEXT_PUBLIC_ 变量,但在请求时运行的服务端代码只有在服务器启动时设置了这些变量才能看到它们。

由于复制的文件会随 standalone 输出一起提供,请只在其中保留非机密的默认值,并在启动 server.js 时将机密信息作为环境变量提供,例如通过托管平台的环境设置或密钥管理器。Docker 示例遵循此方法,使用 .dockerignore 将 .env 排除在构建上下文之外。

此复制与文件追踪是分开的,因此 outputFileTracingExcludes 不会移除这些文件。要移除它们,请在 next build 之后删除:

Terminal
rm -f .next/standalone/.env .next/standalone/.env.production

小知识:删除这些文件也会移除其回退值,因此请设置服务器运行时需要的每一个变量。当 outputFileTracingRoot 指向项目目录之上时,文件会相对于该根目录复制,例如 .next/standalone/packages/web-app/.env。

注意事项#

  • 在 monorepo 设置中进行追踪时,默认使用项目目录作为追踪根目录。对于 next build packages/web-app,packages/web-app 将是追踪根目录,该文件夹之外的任何文件都不会被包含。要包含此文件夹之外的文件,你可以在 next.config.js 中设置 outputFileTracingRoot。
packages/web-app/next.config.js
const path = require('path')

module.exports = {
  // 这会包含往上两级目录的 monorepo 根目录中的文件
  outputFileTracingRoot: path.join(__dirname, '../../'),
}
  • 在某些情况下,Next.js 可能无法包含所需的文件,或可能错误地包含未使用的文件。在这些情况下,你可以分别在 next.config.js 中使用 outputFileTracingIncludes 和 outputFileTracingExcludes。每个选项都接受一个对象,其键是 路由 glob(使用 picomatch 与路由路径匹配,例如 /api/hello),其值是从项目根目录解析的 glob 模式,用于指定要在追踪中包含或排除的文件。

小知识: 在 monorepo 中,project root 指的是 Next.js 项目根目录(包含 next.config.js 的文件夹,例如 packages/web-app),而不一定是 monorepo 根目录。

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

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

  • 键仍然匹配路由路径('/api/hello'、'/products/[id]' 等)。
  • 值可以引用 src/ 下的路径,因为它们是相对于项目根目录解析的。
next.config.js
module.exports = {
  outputFileTracingIncludes: {
    '/products/*': ['src/lib/payments/**/*'],
    '/*': ['src/config/runtime/**/*.json'],
  },
  outputFileTracingExcludes: {
    '/api/*': ['src/temp/**/*', 'public/large-logs/**/*'],
  },
}

你也可以使用像 '/*' 这样的全局键来匹配所有路由:

next.config.js
module.exports = {
  outputFileTracingIncludes: {
    '/*': ['src/i18n/locales/**/*.json'],
  },
}

这些选项应用于服务端追踪,不会影响不生成服务端追踪文件的路由:

  • Edge Runtime 路由不受影响。
  • 完全静态的页面不受影响。

它们也不会影响 standalone 输出复制的 .env 和 .env.production 文件。请参阅环境变量文件。

standalone 输出还会复制生产服务器追踪(.next/next-server.js.nft.json)中的文件。对于此追踪,排除键是与名称 next-server 匹配的,而不是路由路径,因此以斜杠开头的路由 glob(如 '/*')不适用于它。要从该追踪中排除文件,请在 outputFileTracingExcludes 中使用 'next-server' 键。此键仅支持用于排除:

next.config.js
module.exports = {
  outputFileTracingExcludes: {
    // 路由追踪
    '/*': ['./scripts/**/*'],
    // 生产服务器追踪
    'next-server': ['./scripts/**/*'],
  },
}

在 monorepo 中,或当你需要包含 app 文件夹之外的文件时,可以将 outputFileTracingRoot 与 includes 结合使用:

next.config.js
const path = require('path')

module.exports = {
  // 从 monorepo 根目录开始追踪
  outputFileTracingRoot: path.join(__dirname, '../../'),
  outputFileTracingIncludes: {
    '/route1': ['../shared/assets/**/*'],
  },
}

小知识:

  • 为了跨平台兼容性,在模式中优先使用正斜杠(/)。
  • 尽量保持模式狭窄,以避免追踪结果过大(避免在仓库根目录使用 **/*)。

用于原生/运行时资源的常见 include 模式:

next.config.js
module.exports = {
  outputFileTracingIncludes: {
    '/*': ['node_modules/sharp/**/*', 'node_modules/aws-crt/dist/bin/**/*'],
  },
}
Next.js 中文网