instrumentation-client.js

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

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

用法

与 server-side instrumentation 不同，您无需导出任何特定函数。您可以直接在文件中编写监控代码：

typescript

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

javascript

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

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

路由导航跟踪

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

typescript

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

javascript

performance.mark('app-init')

export function onRouterTransitionStart(url, navigationType) {
  console.log(`Navigation started: ${navigationType} to ${url}`)
  performance.mark(`nav-start-${Date.now()}`)
}

onRouterTransitionStart 函数接收两个参数：

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

性能考量

保持埋点代码轻量。

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

执行时机

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

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

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

示例

错误跟踪

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

typescript

import Monitor from './lib/monitoring'

Monitor.initialize()

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

javascript

import Monitor from './lib/monitoring'

Monitor.initialize()

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

分析跟踪

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

typescript

import { analytics } from './lib/analytics'

analytics.init()

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

javascript

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 和性能标记跟踪交互时间 (Time to Interactive) 和导航性能。

typescript

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

javascript

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

在应用程序代码运行之前加载 polyfills。使用静态导入进行即时加载，并使用动态导入进行基于特性检测的条件加载。

typescript

import './lib/polyfills'

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

javascript

import './lib/polyfills'

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

版本历史

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

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

用法

与 server-side instrumentation 不同，您无需导出任何特定函数。您可以直接在文件中编写监控代码：

typescript

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

javascript

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

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

路由导航跟踪

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

typescript

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

javascript

performance.mark('app-init')

export function onRouterTransitionStart(url, navigationType) {
  console.log(`Navigation started: ${navigationType} to ${url}`)
  performance.mark(`nav-start-${Date.now()}`)
}

onRouterTransitionStart 函数接收两个参数：

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

性能考量

保持埋点代码轻量。

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

执行时机

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

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

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

示例

错误跟踪

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

typescript

import Monitor from './lib/monitoring'

Monitor.initialize()

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

javascript

import Monitor from './lib/monitoring'

Monitor.initialize()

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

分析跟踪

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

typescript

import { analytics } from './lib/analytics'

analytics.init()

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

javascript

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 和性能标记跟踪交互时间 (Time to Interactive) 和导航性能。

typescript

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

javascript

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

在应用程序代码运行之前加载 polyfills。使用静态导入进行即时加载，并使用动态导入进行基于特性检测的条件加载。

typescript

import './lib/polyfills'

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

javascript

import './lib/polyfills'

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

版本历史

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

文档导航

用法

路由导航跟踪

性能考量

执行时机

示例

错误跟踪

分析跟踪

性能监控

Polyfills

版本历史

用法

路由导航跟踪

性能考量

执行时机

示例

错误跟踪

分析跟踪

性能监控

Polyfills

版本历史