NNext.js 中文网 GitHub

输出类型

向适配器公开的所有构建输出类型的参考。

outputs 对象包含构建输出类型的数组:

  • outputs.pages:来自 pages/ 目录的 React 页面
  • outputs.pagesApi:来自 pages/api/ 的 API 路由
  • outputs.appPages:来自 app/ 目录的 React 页面
  • outputs.appRoutes:来自 app/ 的 API 和元数据路由
  • outputs.prerenders:启用 ISR 的路由和静态预渲染
  • outputs.staticFiles:静态资源和自动静态优化的页面
  • outputs.middleware:Middleware 函数(如果存在)

注意: 当 config.output 设为 'export' 时,只有 outputs.staticFiles 会被填充。所有其他数组(pages、appPages、pagesApi、appRoutes、prerenders)都为空,因为整个应用都作为静态文件导出。

对于任何带有 runtime: 'edge' 的路由输出,都包含 edgeRuntime,其中含有用于在您的 edge runtime 中调用该输出的规范条目元数据。请注意,Edge Runtime 已弃用。

页面(outputs.pages)#

来自 pages/ 目录的 React 页面:

typescript
{
  type: 'PAGES'
  id: string           // 路由标识符
  filePath: string     // 构建文件的路径
  pathname: string     // URL 路径名
  sourcePage: string   // pages/ 目录中的原始源文件路径
  runtime: 'nodejs' | 'edge'
  assets: Record<string, string>  // 追踪到的依赖项(键:相对于仓库根目录的路径,值:绝对路径)
  assetsHashes: Record<string, string>  // 每个 `assets` 条目的内容哈希(键:与 `assets` 相同,值:内容哈希)
  wasmAssets?: Record<string, string>  // 打包的 wasm 文件(键:名称,值:绝对路径)
  edgeRuntime?: {
    modulePath: string    // 在 edge runtime 中注册的模块的绝对路径
    entryKey: string      // edge 条目注册表使用的规范键
    handlerExport: string // 要调用的导出名称,当前为 'handler'
  }
  config: {
    maxDuration?: number  // 路由的最大持续时间(秒)
    preferredRegion?: string | string[]  // 首选部署区域(已弃用)
    env?: Record<string, string>  // 环境变量(仅限 edge runtime)
  }
}

API 路由(outputs.pagesApi)#

来自 pages/api/ 的 API 路由:

typescript
{
  type: 'PAGES_API'
  id: string           // 路由标识符
  filePath: string     // 构建文件的路径
  pathname: string     // URL 路径名
  sourcePage: string   // 原始相对源文件路径
  runtime: 'nodejs' | 'edge'
  assets: Record<string, string>  // 追踪到的依赖项(键:相对于仓库根目录的路径,值:绝对路径)
  assetsHashes: Record<string, string>  // 每个 `assets` 条目的内容哈希(键:与 `assets` 相同,值:内容哈希)
  wasmAssets?: Record<string, string>  // 打包的 wasm 文件(键:名称,值:绝对路径)
  edgeRuntime?: {
    modulePath: string    // 在 edge runtime 中注册的模块的绝对路径
    entryKey: string      // edge 条目注册表使用的规范键
    handlerExport: string // 要调用的导出名称,当前为 'handler'
  }
  config: {
    maxDuration?: number  // 路由的最大持续时间(秒)
    preferredRegion?: string | string[]  // 首选部署区域(已弃用)
    env?: Record<string, string>  // 环境变量(仅限 edge runtime)
  }
}

App 页面(outputs.appPages)#

来自 app/ 目录的 React 页面:

typescript
{
  type: 'APP_PAGE'
  id: string           // 路由标识符
  filePath: string     // 构建文件的路径
  pathname: string     // URL 路径名。RSC 路由包含 .rsc 后缀
  sourcePage: string   // 原始相对源文件路径
  runtime: 'nodejs' | 'edge' // 路由构建的目标运行时
  assets: Record<string, string>  // 追踪到的依赖项(键:相对于仓库根目录的路径,值:绝对路径)
  assetsHashes: Record<string, string>  // 每个 `assets` 条目的内容哈希(键:与 `assets` 相同,值:内容哈希)
  wasmAssets?: Record<string, string>  // 打包的 wasm 文件(键:名称,值:绝对路径)
  edgeRuntime?: {
    modulePath: string    // 在 edge runtime 中注册的模块的绝对路径
    entryKey: string      // edge 条目注册表使用的规范键
    handlerExport: string // 要调用的导出名称,当前为 'handler'
  }
  config: {
    maxDuration?: number  // 路由的最大持续时间(秒)
    preferredRegion?: string | string[]  // 首选部署区域(已弃用)
    env?: Record<string, string>  // 环境变量(仅限 edge runtime)
  }
}

App 路由(outputs.appRoutes)#

来自 app/ 目录的 API 和元数据路由:

typescript
{
  type: 'APP_ROUTE'
  id: string           // 路由标识符
  filePath: string     // 构建文件的路径
  pathname: string     // URL 路径名
  sourcePage: string   // 原始相对源文件路径
  runtime: 'nodejs' | 'edge' | 'go' // 路由构建的目标运行时
  assets: Record<string, string>  // 追踪到的依赖项(键:相对于仓库根目录的路径,值:绝对路径)
  assetsHashes: Record<string, string>  // 每个 `assets` 条目的内容哈希(键:与 `assets` 相同,值:内容哈希)
  wasmAssets?: Record<string, string>  // 打包的 wasm 文件(键:名称,值:绝对路径)
  edgeRuntime?: {
    modulePath: string    // 在 edge runtime 中注册的模块的绝对路径
    entryKey: string      // edge 条目注册表使用的规范键
    handlerExport: string // 要调用的导出名称,当前为 'handler'
  }
  config: {
    maxDuration?: number  // 路由的最大持续时间(秒)
    preferredRegion?: string | string[]  // 首选部署区域(已弃用)
    env?: Record<string, string>  // 环境变量(仅限 edge runtime)
  }
}

借助实验性的 route.go 约定,App Router 的 Go 处理程序使用 runtime: 'go'。现有的 filePath 指向已编译的 HTTP 服务器可执行文件,sourcePage 保持与 Node.js 输出相同的源路由标识。没有引入新的输出键。Go 输出不会在 assets 中包含共享的 Node.js 运行时文件。

支持 Go 的适配器必须为兼容的操作系统和架构打包该可执行文件及声明的资源,然后在设置 PORT 的情况下启动其服务器。每个 Go 处理程序都是独立生成的;Go 页面、middleware 和预渲染父级不属于此实验。请参阅调用入口点。

预渲染(outputs.prerenders)#

启用 ISR 的路由和静态预渲染:

typescript
{
  type: 'PRERENDER'
  id: string           // 路由标识符
  pathname: string     // URL 路径名
  parentOutputId: string  // 源页面/路由的 ID
  groupId: number        // 重新验证组标识符(具有相同 groupId 的预渲染一起重新验证)
  route: string           // 与文件系统路由对齐的源路由匹配器,保留动态段(例如 /blog/[slug] 对应预渲染路径 /blog/first)
  routeType?: 'route' | 'fallback' | 'shell' | 'page'  // 规范响应的种类
  response?: 'empty' | 'initial' | 'complete'  // 请求时工作之前的完整程度
  compute?: 'blocking' | 'dynamic' | 'resuming' | 'static'  // 用于提供输出的计算模式(请求时)
  htmlSize?: number       // 预渲染的 App Router HTML shell 的字节大小
  pprChain?: {
    headers: Record<string, string>  // PPR 链标头(例如 'next-resume': '1')
  }
  parentFallbackMode?: false | null | string  // false:无额外路径(fallback: false),null:阻塞渲染,string:HTML fallback 的路径
  fallback?: {
    filePath: string | undefined  // fallback 文件的路径(HTML、JSON 或 RSC)
    initialStatus?: number  // 初始状态码
    initialHeaders?: Record<string, string | string[]>  // 初始标头
    initialExpiration?: number  // 初始过期时间(秒)
    initialRevalidate?: number | false  // 初始重新验证时间(秒),完全静态时为 false
    postponedState: string | undefined  // 用于恢复渲染的序列化 PPR 状态
  }
  config: {
    allowQuery?: string[]     // 视为缓存键的允许查询参数
    allowHeader?: string[]    // ISR 允许的标头
    bypassFor?: RouteHas[]    // 缓存绕过条件
    renderingMode?: 'STATIC' | 'PARTIALLY_STATIC'  // STATIC:完全静态,PARTIALLY_STATIC:启用 PPR
    partialFallback?: boolean  // 提供部分 fallback shell,并应在后台升级为完整路由
    bypassToken?: string      // 生成的令牌,表示应绕过预渲染缓存
  }
}

预渲染分类#

routeType、response 和 compute 会一起出现在预渲染组中的主响应上,以及完整路由的 App Router RSC 输出上。HTML 和 RSC 输出各自有独立的分类。Pages Router 的数据输出和静态路由段预取输出会省略这些字段。对于使用 fallback: false 的动态路由模式,其预渲染输出也会省略分类,因为它们不提供在构建时未预渲染的路径。

routeType 标识规范响应的种类:

  • route:非 UI 路由,例如 Route Handler
  • page:URL 中没有缺失的可预渲染参数的页面
  • shell:针对其 URL 类别最具体的可复用页面 shell
  • fallback:可通过填充更多可预渲染参数来特化的可复用页面响应

response 描述在请求时工作之前响应的完整程度:

  • empty:无法提供初始页面响应
  • initial:可以提供初始响应,但它不是完整的页面 UI。实际上,这仅适用于部分可预渲染的 UI 路由
  • complete:响应是完整的;这可以包括零字节的响应体,例如 204 Route Handler 响应

empty 响应并不意味着缓存未命中。预渲染可以没有初始 HTML,但仍能提供缓存的延迟状态用于请求时渲染。

compute 描述用于提供输出的计算模式(请求时):

  • blocking:当没有可用的缓存预渲染时,响应必须等待预渲染或重新验证。最终的输出仍可能需要请求时的服务端工作
  • dynamic:请求时渲染产生响应的首批字节,而无需先进行必需的预渲染。响应可以在渲染继续时进行流式传输
  • resuming:在服务器上恢复延迟工作的同时提供初始响应
  • static:生成的输出不需要按请求进行服务端渲染。预渲染缺失或过期仍可能需要生成或重新验证

当服务器无需先等待单独的预渲染即可渲染请求时,空的 PPR shell 使用 response: 'empty' 和 compute: 'dynamic'。这既适用于具体的构建路径,也适用于动态路由模式。平台可以利用此分类,在后台预渲染的同时动态渲染缓存未命中的响应。例如,instant = false 允许空 shell,但不要求阻塞式预渲染。

对于处理构建时未生成路径的匹配器,显式的阻塞参数匹配策略使用 response: 'empty' 和 compute: 'blocking'。当按需预渲染过期或被淘汰时,即使缓存结果只是部分的,该策略同样适用。仍然可用的过期预渲染遵循既有的"陈旧时重新验证"行为。构建时生成的具体路径使用其自身预渲染输出的分类。

当经过分类的完整路由 RSC 输出包含完整的可复用 RSC 载荷时,使用 response: 'complete' 和 compute: 'static'。需要在请求时进行 RSC 渲染的输出通常使用 response: 'empty' 和 compute: 'dynamic'。渲染可以在完成前流式传输。缓存的延迟状态可以为该渲染提供数据,但它不是初始 RSC 响应,也不会使输出成为 resuming。

对于 ensureStatic = 'navigation' 的路由,凡是覆盖构建时未生成路径的 HTML 和完整路由 RSC 输出(例如 /products/[slug] 和 /products/[slug].rsc),都使用 response: 'empty' 和 compute: 'static'。这些输出没有 fallback 响应。平台必须等待 Next.js 预渲染新路径后才能提供其响应。生成的输出不需要按请求进行服务端渲染。如果该路径需要动态服务端工作,则预渲染会验证失败。具体的构建路径同样使用 compute: 'static',并带有 complete 的完整路由 RSC 响应。它们的 HTML 响应可以是 complete,也可以在 UI 于浏览器中完成时为 initial。

对于显式阻塞的参数匹配器,其完整路由 RSC 输出使用 response: 'empty' 和 compute: 'blocking'。平台必须先生成可用的预渲染,然后才能提供响应,包括在按需结果过期或被淘汰时。生成的结果仍可能需要请求时的 RSC 渲染。具体的构建路径会使用其自身的分类,而不是继承未知参数策略。

HTML 响应可以是 initial,而其 RSC 输出是 complete,例如当 Client Component 在浏览器中解析某个 Suspense 边界时。一个完整的通用 HTML shell 也可能对应 empty 的 RSC 输出,当其 Flight 路由树仍需要具体的路由参数时就是如此。

htmlSize 仅包含在主要的 App Router HTML 输出上。值为 0 表示 HTML shell 为空。Pages Router 的预渲染、Route Handlers 以及相关的 RSC、数据和路由段输出会省略它。

静态文件(outputs.staticFiles)#

静态资源和自动静态优化的页面:

typescript
{
  type: 'STATIC_FILE'
  id: string // 此静态文件输出的唯一标识符
  filePath: string // 构建文件的绝对文件系统路径
  pathname: string // 此静态文件的可路由 URL 路径名
  immutableHash: string | undefined // 当文件名包含哈希时的内容哈希,表示该文件是不可变的
}

有关 immutableHash 的更多信息,请参阅支持不可变静态资源。

Middleware(outputs.middleware)#

middleware.ts(.js/.ts)或 proxy.ts(.js/.ts)函数(如果存在):

typescript
{
  type: 'MIDDLEWARE'
  id: string           // 路由标识符
  filePath: string     // 构建文件的路径
  pathname: string      // 始终为 '/_middleware'
  sourcePage: string    // 始终为 'middleware'
  runtime: 'nodejs' | 'edge' // 路由构建的目标运行时
  assets: Record<string, string>  // 追踪到的依赖项(键:相对于仓库根目录的路径,值:绝对路径)
  assetsHashes: Record<string, string>  // 每个 `assets` 条目的内容哈希(键:与 `assets` 相同,值:内容哈希)
  wasmAssets?: Record<string, string>  // 打包的 wasm 文件(键:名称,值:绝对路径)
  edgeRuntime?: {
    modulePath: string    // 在 edge runtime 中注册的模块的绝对路径
    entryKey: string      // edge 条目注册表使用的规范键
    handlerExport: string // 要调用的导出名称,当前为 'handler'
  }
  config: {
    maxDuration?: number  // 路由的最大持续时间(秒)
    preferredRegion?: string | string[]  // 首选部署区域(已弃用)
    env?: Record<string, string>  // 环境变量(仅限 edge runtime)
    matchers?: Array<{
      source: string  // 源模式
      sourceRegex: string  // 用于匹配请求的编译后正则表达式
      has: RouteHas[] | undefined  // 正向匹配条件
      missing: RouteHas[] | undefined  // 负向匹配条件
    }>
  }
}
Next.js 中文网