instrumentation.js
instrumentation.js|ts 文件用于将可观测性工具集成到您的应用中，使您能够追踪性能和行为，并在生产环境中调试问题。
要使用该文件，请将其放置在应用的根目录下，或者如果使用了 src 文件夹，则放置在该文件夹内。
导出项
register (可选)
该文件导出一个 register 函数，该函数在初始化新的 Next.js 服务器实例时仅调用一次。register 可以是一个异步函数。
import { registerOTel } from '@vercel/otel'
export function register() {
registerOTel('next-app')
}import { registerOTel } from '@vercel/otel'
export function register() {
registerOTel('next-app')
}onRequestError (可选)
您可以选择导出一个 onRequestError 函数，用于将服务器错误追踪到任何自定义的可观测性提供程序。
- 如果在
onRequestError中运行任何异步任务，请确保它们被await。onRequestError将在 Next.js 服务器捕获错误时触发。 error实例可能不是抛出的原始错误实例，因为如果错误在服务端组件 (Server Components) 渲染过程中发生，可能会被 React 处理。如果发生这种情况，您可以使用错误上的digest属性来识别实际的错误类型。
import { type Instrumentation } from 'next'
export const onRequestError: Instrumentation.onRequestError = async (
err,
request,
context
) => {
await fetch('https://.../report-error', {
method: 'POST',
body: JSON.stringify({
message: err.message,
request,
context,
}),
headers: {
'Content-Type': 'application/json',
},
})
}export async function onRequestError(err, request, context) {
await fetch('https://.../report-error', {
method: 'POST',
body: JSON.stringify({
message: err.message,
request,
context,
}),
headers: {
'Content-Type': 'application/json',
},
})
}参数
该函数接受三个参数：error、request 和 context。
export function onRequestError(
error: { digest: string } & Error,
request: {
path: string // 资源路径，例如 /blog?name=foo
method: string // 请求方法，例如 GET、POST 等
headers: { [key: string]: string }
},
context: {
routerKind: 'Pages Router' | 'App Router' // 路由类型
routePath: string // 路由文件路径，例如 /app/blog/[dynamic]
routeType: 'render' | 'route' | 'action' | 'middleware' // 发生错误的上下文
renderSource:
| 'react-server-components'
| 'react-server-components-payload'
| 'server-rendering'
revalidateReason: 'on-demand' | 'stale' | undefined // undefined 表示没有重新验证的正常请求
renderType: 'dynamic' | 'dynamic-resume' // 'dynamic-resume' 用于 PPR
}
): void | Promise<void>error: 捕获的错误本身（类型始终为Error），以及一个digest属性，这是错误的唯一 ID。request: 与错误关联的只读请求信息。context: 发生错误的上下文。这可以是路由类型（App 或 Pages Router），和/或（服务端组件 ('render')、路由处理器 ('route')、服务端操作 ('action') 或中间件 ('middleware')）。
指定运行时
instrumentation.js 文件在 Node.js 和 Edge 运行时中均可工作，但您可以使用 process.env.NEXT_RUNTIME 来指定特定的运行时。
export function register() {
if (process.env.NEXT_RUNTIME === 'edge') {
return require('./register.edge')
} else {
return require('./register.node')
}
}
export function onRequestError() {
if (process.env.NEXT_RUNTIME === 'edge') {
return require('./on-request-error.edge')
} else {
return require('./on-request-error.node')
}
}版本历史
| 版本 | 变更内容 |
|---|---|
v15.0.0 | 引入 onRequestError，instrumentation 功能稳定 |
v14.0.4 | 为 instrumentation 提供 Turbopack 支持 |
v13.2.0 | instrumentation 作为实验性功能引入 |