NNext.js 中文网 GitHub

如何设置 instrumentation

了解如何使用 instrumentation 在 Next.js 应用的服务器启动时运行代码

Instrumentation 是使用代码将监控和日志工具集成到应用程序中的过程。这使你能够跟踪应用程序的性能和行为,并调试生产环境中的问题。

约定#

要设置 instrumentation,请在项目的根目录中(如果使用 src 文件夹,则在其内部)创建 instrumentation.ts|js 文件。

然后,在该文件中导出一个 register 函数。当新的 Next.js 服务器实例启动时,此函数将被调用一次,并且必须在服务器准备好处理请求之前完成。

例如,要将 Next.js 与 OpenTelemetry 和 @vercel/otel 一起使用:

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

有关完整的实现,请参阅 Next.js 与 OpenTelemetry 示例。

小知识:

  • instrumentation 文件应位于项目的根目录,而不是 app 或 pages 目录内。如果你使用 src 文件夹,则将该文件放在 src 中,与 pages 和 app 并列。
  • 如果你使用 pageExtensions 配置选项 添加后缀,则还需要相应地更新 instrumentation 的文件名。

示例#

导入有副作用的文件#

有时,在代码中导入某个文件是因为它会产生副作用,这很有用。例如,你可能导入一个定义了一组全局变量的文件,但从未在代码中显式使用该导入的文件。你仍然可以访问该包声明的全局变量。

我们建议在 register 函数中使用 JavaScript import 语法导入文件。以下示例演示了在 register 函数中使用 import 的基本用法:

instrumentation.ts
export async function register() {
  await import('package-with-side-effect')
}
instrumentation.js
export async function register() {
  await import('package-with-side-effect')
}

小知识:

我们建议在 register 函数内部导入文件,而不是在文件顶部导入。通过这样做,你可以将所有副作用集中放在代码中的一处,并避免在文件顶部全局导入可能带来的任何意外后果。

导入特定于运行时的代码#

Next.js 会在所有环境中调用 register,因此对于不支持特定运行时(例如 Edge 或 Node.js)的代码,进行条件导入非常重要。你可以使用 NEXT_RUNTIME 环境变量来获取当前环境:

instrumentation.ts
export async function register() {
  if (process.env.NEXT_RUNTIME === 'nodejs') {
    await import('./instrumentation-node')
  }

  if (process.env.NEXT_RUNTIME === 'edge') {
    await import('./instrumentation-edge')
  }
}
instrumentation.js
export async function register() {
  if (process.env.NEXT_RUNTIME === 'nodejs') {
    await import('./instrumentation-node')
  }

  if (process.env.NEXT_RUNTIME === 'edge') {
    await import('./instrumentation-edge')
  }
}
Next.js 中文网