instrumentation-client.js

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

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

用法

与服务器端 instrumentation 不同，您不需要导出任何特定的函数。您可以直接在文件中编写监控代码。

// Set up performance monitoring
performance.mark('app-init')
 
// Initialize analytics
console.log('Analytics initialized')
 
// Set up error tracking
window.addEventListener('error', (event) => {
  // Send to your error tracking service
  reportError(event.error)
})

错误处理： 在您的 instrumentation 代码周围实现 try-catch 块，以确保稳健的监控。这可以防止单个追踪失败影响其他 instrumentation 功能。

您可以导出一个 onRouterTransitionStart 函数，以便在导航开始时接收通知。

performance.mark('app-init')
 
export function onRouterTransitionStart(
  url: string,
  navigationType: 'push' | 'replace' | 'traverse'
) {
  console.log(`Navigation started: ${navigationType} to ${url}`)
  performance.mark(`nav-start-${Date.now()}`)
}

onRouterTransitionStart 函数接收两个参数：

url: string - 正在导航到的 URL。
navigationType: 'push' | 'replace' | 'traverse' - 导航的类型。

性能考虑

保持 instrumentation 代码轻量。

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

执行时机

instrumentation-client.js 文件在应用程序生命周期的特定时刻执行：

HTML 文档加载之后
React 水合作用开始之前
用户交互可能发生之前

这个时机非常适合设置错误追踪、分析和性能监控，以便捕获早期的应用程序生命周期事件。

示例

错误追踪

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

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

分析追踪

初始化分析并使用详细的元数据追踪导航事件，以便进行用户行为分析。

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

性能监控

使用 Performance Observer API 和性能标记追踪交互时间 (Time to Interactive) 和导航性能。

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}`)
}

Polyfills

在应用程序代码运行前加载 Polyfills。对于立即加载使用静态导入，对于基于特性检测的条件加载使用动态导入。

import './lib/polyfills'
 
if (!window.ResizeObserver) {
  import('./lib/polyfills/resize-observer').then((mod) => {
    window.ResizeObserver = mod.default
  })
}

版本历史

版本	更改
`v15.3`	引入 `instrumentation-client`