NNext.js 中文网 GitHub

instrumentation.js

instrumentation.js 文件的 API 参考。

instrumentation.js|ts 文件用于将可观测性工具集成到您的应用中,使您能够跟踪性能和行为,并调试生产环境中的问题。

要使用它,请将该文件放在应用的根目录中,或者如果使用了 src 文件夹,则放在其中。

导出#

register(可选)#

该文件导出一个 register 函数,当新的 Next.js 服务器实例启动时会调用一次,并且必须在服务器准备好处理请求之前完成。register 可以是异步函数。

instrumentation.ts
import { registerOTel } from '@vercel/otel'

export function register() {
  registerOTel('next-app')
}
instrumentation.js
import { registerOTel } from '@vercel/otel'

export function register() {
  registerOTel('next-app')
}

onRequestError(可选)#

您可以选择导出 onRequestError 函数,将服务器错误跟踪到任何自定义的可观测性提供者。

  • 如果您在 onRequestError 中运行任何异步任务,请确保等待它们完成。当 Next.js 服务器捕获错误时,将触发 onRequestError。
  • error 实例可能不是抛出的原始错误实例,因为如果在服务器组件渲染期间遇到该错误,React 可能会对其进行处理。如果发生这种情况,您可以使用错误的 digest 属性来识别实际错误类型。
instrumentation.ts
import { type Instrumentation } from 'next'

export const onRequestError: Instrumentation.onRequestError = async (
  err,
  request,
  context
) => {
  const message = err instanceof Error ? err.message : String(err)
  const digest =
    typeof err === 'object' && err !== null && 'digest' in err
      ? String(err.digest)
      : undefined

  await fetch('https://.../report-error', {
    method: 'POST',
    body: JSON.stringify({
      message,
      digest,
      request,
      context,
    }),
    headers: {
      'Content-Type': 'application/json',
    },
  })
}
instrumentation.js
export async function onRequestError(err, request, context) {
  const message = err instanceof Error ? err.message : String(err)
  const digest =
    typeof err === 'object' && err !== null && 'digest' in err
      ? String(err.digest)
      : undefined

  await fetch('https://.../report-error', {
    method: 'POST',
    body: JSON.stringify({
      message,
      digest,
      request,
      context,
    }),
    headers: {
      'Content-Type': 'application/json',
    },
  })
}

参数#

该函数接受三个参数:error、request 和 context。

Types
export function onRequestError(
  error: unknown,
  request: {
    path: string // 资源路径,例如 /blog?name=foo
    method: string // 请求方法,例如 GET、POST 等
    headers: { [key: string]: string | string[] }
  },
  context: {
    routerKind: 'Pages Router' | 'App Router' // 路由器类型
    routePath: string // 路由文件路径,例如 /app/blog/[dynamic]
    routeType: 'render' | 'route' | 'action' | 'proxy' // 发生错误的上下文
    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:捕获的值类型为 unknown。在读取 message 或 digest 等属性之前,请先缩小其类型。
  • request:与错误关联的只读请求信息。
  • context:发生错误的上下文。这可以是路由器类型(App Router 或 Pages Router),和/或(服务器组件(render)、Route Handler(route)、Server Action(action)或 Proxy(proxy))。

指定运行时#

instrumentation.js 文件在 Node.js 和 Edge 运行时中均可工作,但您可以使用 process.env.NEXT_RUNTIME 来指定特定的运行时。

instrumentation.js
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.4Turbopack 支持 instrumentation
v13.2.0instrumentation 作为实验性功能引入
Next.js 中文网