NNext.js 中文网 GitHub

instrumentation-client.js

了解如何添加客户端 instrumentation 以跟踪和监控 Next.js 应用的前端性能。

instrumentation-client.js|ts 文件允许你添加监控、分析代码,以及在应用变为可交互之前运行的其他副作用。这对于设置性能跟踪、错误监控、polyfill 或任何其他客户端可观测性工具非常有用。

要使用它,请将文件放在应用的根目录或 src 文件夹中。

用法#

与服务端 instrumentation 不同,你无需导出任何特定函数。你可以直接在文件中编写监控代码:

instrumentation-client.ts
// 设置性能监控
performance.mark('app-init')

// 初始化分析
console.log('Analytics initialized')

// 设置错误追踪
window.addEventListener('error', (event) => {
  // 发送到你的错误追踪服务
  reportError(event.error)
})
instrumentation-client.js
// 设置性能监控
performance.mark('app-init')

// 初始化分析
console.log('Analytics initialized')

// 设置错误追踪
window.addEventListener('error', (event) => {
  // 发送到你的错误追踪服务
  reportError(event.error)
})

错误处理: 在 instrumentation 代码周围实现 try-catch 块,以确保监控的健壮性。这可以防止单个跟踪失败影响其他 instrumentation 功能。

路由导航跟踪#

你可以导出 onRouterTransitionStart 来观察 App Router 导航的开始:

instrumentation-client.ts
export function onRouterTransitionStart(
  url: string,
  navigationType: 'push' | 'replace' | 'traverse'
) {
  console.log(url, navigationType)
}

额外的路由转场信息处于实验阶段。启用它可以接收第三个 event 参数:

next.config.ts
import type { NextConfig } from 'next'

const nextConfig: NextConfig = {
  experimental: {
    instrumentationClientRouterTransitionEvents: true,
  },
}

export default nextConfig

该 event 包含导航分派时已知的转场元数据和来源上下文:

instrumentation-client.ts
import type { RouterTransitionStartEvent, RouterTransitionType } from 'next'

export function onRouterTransitionStart(
  url: string,
  navigationType: RouterTransitionType,
  { id, timestamp, fromRoutes, prefetchIntent }: RouterTransitionStartEvent
) {
  console.log(id, timestamp, url, navigationType, fromRoutes, prefetchIntent)
}
instrumentation-client.js
export function onRouterTransitionStart(url, navigationType, event) {
  console.log(
    event.id,
    event.timestamp,
    url,
    navigationType,
    event.fromRoutes,
    event.prefetchIntent
  )
}

onRouterTransitionStart 接收:

  • url: string - 要导航到的 URL
  • navigationType: 'push' | 'replace' | 'traverse' - 导航类型
  • event.id - 此次转场的事件共享的不透明 ID
  • event.timestamp - 框架捕获的 Unix 时间戳(毫秒)
  • event.fromRoutes - 导航前可见的路由模式。主 children 路由在前,其后是按确定顺序排列的并行 slot
  • event.prefetchIntent - 对于链接导航,表示被点击的链接是请求了完整预取(full)、使用了自动预取(auto),还是未请求预取(none)。对于没有关联链接的导航(编程式 router.push()/router.replace(),或浏览器前进/后退),该值为 null,因为没有适用的链接预取意图

路由条目使用文件系统风格的模式,因此从 /blog/hello 离开的导航可能会报告 /blog/[slug]。

Hook 错误会被隔离,不会影响导航或其他 hook。

性能注意事项#

保持 instrumentation 代码轻量。

Next.js 会在开发环境中监控初始化时间,如果超过 16ms,就会记录警告,因为这可能会影响页面的流畅加载。

执行时机#

instrumentation-client.js 文件在应用生命周期中的特定时间点执行:

  1. 在 HTML 文档加载之后
  2. 在 React hydration 开始之前
  3. 在用户可进行交互之前

这一时机使其非常适合设置需要捕获应用早期生命周期事件错误追踪、分析和性能监控。

只有同步的顶层代码才能保证在 hydration 之前完成。此处启动的异步工作(一个 Promise、import() 或顶层 await)不会被等待,可能会在 hydration 开始后才解析,因此应将其视为 fire-and-forget。如果某些内容必须在组件运行之前就位,请使用 Polyfills 中的同步模式之一。

另请参阅#

next.config.js 插件(例如 withSentry 之类的包装器)可以通过 instrumentationClientInject 选项注册自己的客户端 instrumentation 模块。注入的模块会按数组顺序在此文件之前运行,并且可以导出相同的路由转场开始 hook。应用代码应继续直接使用此文件约定。

示例#

错误追踪#

在 React 启动之前初始化错误追踪,并添加导航面包屑以获得更好的调试上下文。

instrumentation-client.ts
import Monitor from './lib/monitoring'

Monitor.initialize()

export function onRouterTransitionStart(url: string) {
  Monitor.pushEvent({
    message: `Navigation to ${url}`,
    category: 'navigation',
  })
}
instrumentation-client.js
import Monitor from './lib/monitoring'

Monitor.initialize()

export function onRouterTransitionStart(url) {
  Monitor.pushEvent({
    message: `Navigation to ${url}`,
    category: 'navigation',
  })
}

分析跟踪#

初始化分析并跟踪导航事件,附带详细的元数据用于用户行为分析。

instrumentation-client.ts
import { analytics } from './lib/analytics'

analytics.init()

export function onRouterTransitionStart(url: string, navigationType: string) {
  analytics.track('page_navigation', {
    url,
    type: navigationType,
    timestamp: Date.now(),
  })
}
instrumentation-client.js
import { analytics } from './lib/analytics'

analytics.init()

export function onRouterTransitionStart(url, navigationType) {
  analytics.track('page_navigation', {
    url,
    type: navigationType,
    timestamp: Date.now(),
  })
}

性能监控#

使用 Performance Observer API 和 performance marks 跟踪 Time to Interactive 和导航性能。

instrumentation-client.ts
const startTime = performance.now()

const observer = new PerformanceObserver(
  (list: PerformanceObserverEntryList) => {
    for (const entry of list.getEntries()) {
      if (entry instanceof PerformanceNavigationTiming) {
        console.log('Time to Interactive:', entry.loadEventEnd - startTime)
      }
    }
  }
)

observer.observe({ entryTypes: ['navigation'] })

export function onRouterTransitionStart(url: string) {
  performance.mark(`nav-start-${url}`)
}
instrumentation-client.js
const startTime = performance.now()

const observer = new PerformanceObserver((list) => {
  for (const entry of list.getEntries()) {
    if (entry instanceof PerformanceNavigationTiming) {
      console.log('Time to Interactive:', entry.loadEventEnd - startTime)
    }
  }
})

observer.observe({ entryTypes: ['navigation'] })

export function onRouterTransitionStart(url) {
  performance.mark(`nav-start-${url}`)
}

Polyfills#

如执行时机所述,此处只有同步的顶层代码会在 hydration 之前运行,因此条件式 import() 或顶层 await 可能会在 hydration 已经开始后才解析。

要保证 polyfill 在组件运行之前被应用,请以静态方式导入它,并在特性检测后同步应用它。由于导入是静态的,polyfill 会发送给所有访问者:

instrumentation-client.ts
import ResizeObserverPolyfill from './lib/polyfills/resize-observer'

if (!window.ResizeObserver) {
  window.ResizeObserver = ResizeObserverPolyfill
}

请避免在此处使用条件式 import() 加载 polyfill。这种导入是 fire-and-forget 的,因此 polyfill 可能会在 hydration 已经开始之后才应用,这对你的组件来说可能已经太晚:

instrumentation-client.ts
// 避免这样做:动态导入是 fire-and-forget 的,因此当你的组件运行时
// `ResizeObserver` 可能仍未定义。
if (!window.ResizeObserver) {
  import('./lib/polyfills/resize-observer').then((mod) => {
    window.ResizeObserver = mod.default
  })
}

对于任何按需加载的内容,更推荐在使用该特性的代码中进行 polyfill。有关该策略及其他策略,请参阅自定义 Polyfills。

Next.js 已经为需要的浏览器注入了一组广泛使用的 polyfill 基线(例如 fetch、URL 和 Object.assign),因此你只需为基线之外的特性添加 polyfill。

版本历史#

版本变更
v16.3.0引入实验性路由转场开始事件
v15.3引入 instrumentation-client
Next.js 中文网