NNext.js 中文网 GitHub

调用入口点

使用适配器运行时上下文调用 Node.js 和 Edge 构建入口点。

Node.js 和 Edge 入口点使用 handler(..., ctx) 接口,并具有特定于运行时的请求/响应类型。实验性的 Go 入口点是编译后的 HTTP 服务器。

Node.js runtime(runtime: 'nodejs')#

Node.js 入口点使用以下接口:

typescript
handler(
  req: IncomingMessage,
  res: ServerResponse,
  ctx: {
    waitUntil?: (promise: Promise<void>) => void
    requestMeta?: RequestMeta
  }
): Promise<void>

直接调用 Node.js 入口点时,适配器可以直接在 requestMeta 上传递辅助函数,而无需依赖内部机制。一些受支持的字段是 hostname、revalidate 和 render404:

ts
await handler(req, res, {
  requestMeta: {
    // 从 process.cwd() 到 Next.js 项目目录的相对路径。
    relativeProjectDir: '.',
    // 路由处理器在构造绝对 URL 时使用的可选主机名。
    hostname: '127.0.0.1',
    // 可选的内部 revalidate 函数,避免通过网络进行重新验证
    revalidate: async ({ urlPath, headers, opts }) => {
      // 特定于平台的 revalidate 实现
    },
    // 用于为 pages router `notFound: true` 渲染 404 页面的可选函数
    render404: async (req, res, parsedUrl, setHeaders) => {
      // 特定于平台的 404 渲染实现
    },
  },
})

Next.js 核心中的相关文件:

Edge runtime(runtime: 'edge')(已弃用)#

Edge Runtime 已弃用。新路由应使用 Node.js runtime。

Edge 入口点使用以下接口:

typescript
handler(
  request: Request,
  ctx: {
    waitUntil?: (prom: Promise<void>) => void
    signal?: AbortSignal
    requestMeta?: RequestMeta
  }
): Promise<Response>

其结构与 handler(..., ctx) 保持一致,但 Node.js 和 Edge runtime 使用不同的请求/响应原语。

对于 runtime: 'edge' 的输出,Next.js 还提供 output.edgeRuntime,其中包含调用入口点所需的规范元数据:

typescript
{
  modulePath: string // 注册到 edge runtime 的模块的绝对路径
  entryKey: string // edge 入口注册表使用的规范键
  handlerExport: string // 要调用的导出名称,当前为 'handler'
}

在你的 edge runtime 加载并求值 modulePath 对应的代码块后,使用 entryKey 从全局 edge 入口注册表(globalThis._ENTRIES)读取已注册的条目,然后从该条目调用 handlerExport:

ts
const entry = await globalThis._ENTRIES[output.edgeRuntime.entryKey]
const handler = entry[output.edgeRuntime.handlerExport]
await handler(request, ctx)

请使用 edgeRuntime,而不要从文件名推导注册表键或 handler 名称。

Next.js 核心中的相关文件:

Go runtime(runtime: 'go')#

使用实验性的 route.go handler 时,output.filePath 标识的是原生可执行文件,而非 JavaScript 模块。请根据目标操作系统和架构将其与声明的 assets 一起打包,并保留可执行权限和资源目标路径。

该可执行文件面向构建主机的操作系统和架构,并禁用 CGO。请在与其部署运行时相同的环境中构建。Go 路由不支持交叉编译。

启动该可执行文件时不要传入参数,将 PORT 设置为其分配的 HTTP 端口,并将打包后的函数目录作为其工作目录。服务器监听 0.0.0.0,以便容器和函数入口能够访问它。网络隔离由适配器负责。适配器构建的可执行文件独立于自托管的 Next.js 服务器运行:它既不需要私有的 Next.js 令牌,也不需要由父进程持有的 stdin 管道。

转发经过 rewrites 和 proxy 处理后的最终目标 URL,包括其查询字符串和任何 basePath。例如,对 /alias?sort=asc 的请求被重写为 /users/123 时,必须以 /users/123?sort=asc 的形式到达 Go 服务器。handler 的 r.URL、r.RequestURI 和查询字符串应反映该目标,包括平台执行的任何 URL 规范化。开发和自托管部署使用相同的目标 URL 约定。

每个可执行文件只包含其自身生成的路由模式。它匹配目标路径名,并从中推导出解码后的动态参数和全部捕获参数。转义的斜杠保留在其原始参数片段内。与所生成路由不匹配的路径名会返回 404。

平台负责将请求路由到正确的 Go 函数,并运行其自身的 rewrite 和 proxy 集成。Node.js 输出继续使用其现有的 handler 接口。JavaScript 回调(例如 ctx.waitUntil)无法传递给 Go 进程;初始服务器契约不保证响应后工作的完成。

Next.js 中文网