调用入口点
调用 JavaScript 构建 handler 和实验性的 Go HTTP 服务器入口点。
Node.js 和 Edge 入口点使用 handler(..., ctx) 接口,并具有特定于运行时的请求/响应类型。实验性的 Go 入口点是编译后的 HTTP 服务器。
Node.js runtime(runtime: 'nodejs')#
Node.js 入口点使用以下接口:
handler(
req: IncomingMessage,
res: ServerResponse,
ctx: {
waitUntil?: (promise: Promise<void>) => void
requestMeta?: RequestMeta
}
): Promise<void>直接调用 Node.js 入口点时,适配器可以直接在 requestMeta 上传递辅助函数,而无需依赖内部机制。一些受支持的字段是 hostname、revalidate 和 render404:
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 核心中的相关文件:
packages/next/src/build/templates/app-page.tspackages/next/src/build/templates/app-route.ts- 以及
packages/next/src/build/templates/pages-api.ts
Edge runtime(runtime: 'edge')(已弃用)#
Edge Runtime 已弃用。新路由应使用 Node.js runtime。
Edge 入口点使用以下接口:
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,其中包含调用入口点所需的规范元数据:
{
modulePath: string // 注册到 edge runtime 的模块的绝对路径
entryKey: string // edge 入口注册表使用的规范键
handlerExport: string // 要调用的导出名称,当前为 'handler'
}在你的 edge runtime 加载并求值 modulePath 对应的代码块后,使用 entryKey 从全局 edge 入口注册表(globalThis._ENTRIES)读取已注册的条目,然后从该条目调用 handlerExport:
const entry = await globalThis._ENTRIES[output.edgeRuntime.entryKey]
const handler = entry[output.edgeRuntime.handlerExport]
await handler(request, ctx)请使用 edgeRuntime,而不要从文件名推导注册表键或 handler 名称。
Next.js 核心中的相关文件:
packages/next/src/build/templates/edge-ssr.tspackages/next/src/build/templates/edge-app-route.tspackages/next/src/build/templates/pages-edge-api.ts- 以及
packages/next/src/build/templates/middleware.ts
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 进程;初始服务器契约不保证响应后工作的完成。