仪表化

如果在项目的根目录（或者如果使用了 src 文件夹，则在其中）的 instrumentation.ts（或 .js）文件中导出了一个名为 register 的函数， 我们将在每次新的 Next.js 服务器实例启动时调用该函数。

温馨提示：

• 此功能是实验性的。要使用它，您必须在 next.config.js 中显式选择通过 experimental.instrumentationHook = true;。
• 仪表文件应该位于项目的根目录，而不是在 app 或 pages 目录中。如果使用 src 文件夹，则将文件放在 src 文件夹旁边。
• 如果使用 pageExtensions 配置选项添加后缀，您还需要更新仪表文件的文件名以匹配。
• 我们创建了一个基本的 with-opentelemetry 示例，您可以使用它。
• 当部署您的 register 函数时，它将在每次冷启动时调用（但在每个环境中仅调用一次）。

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

您可以在 instrumentation.ts 中导入具有副作用的文件， 您可能希望在 register 函数中使用，如以下示例所示：

your-project/instrumentation.ts

import { init } from 'package-init'

export function register() {
  init()
}

然而，我们建议在 register 函数内使用 import 来导入具有副作用的文件。 以下示例演示了在 register 函数中使用 import 的基本用法：

your-project/instrumentation.ts

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

通过这样做，您可以将所有具有副作用的代码放在代码中的一个位置，并避免从文件中导入时的任何意外后果。

我们在所有环境中调用 register，因此必须有条件地导入不支持边缘和 nodejs 的任何代码。 您可以使用环境变量 NEXT_RUNTIME 获取当前环境。 导入特定于环境的代码将如下所示：

your-project/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')
  }
}