Instrumentation | Next.js

如果您從專案的根目錄（或如果使用 src 資料夾則在該資料夾內）的 instrumentation.ts（或 .js）檔案中匯出名為 register 的函數，我們將在每次啟動新的 Next.js 伺服器實例時呼叫該函數。

須知事項

此功能為實驗性。要使用它，您必須在 next.config.js 中明確設定 experimental.instrumentationHook = true; 來啟用。

instrumentation 檔案應位於專案的根目錄，而非 app 或 pages 目錄內。如果您使用 src 資料夾，則將檔案放在 src 內與 pages 和 app 同層的位置。

如果您使用 pageExtensions 設定選項來新增副檔名，則也需要相應地更新 instrumentation 的檔案名稱。

我們已建立一個基本的 with-opentelemetry 範例供您參考。

當您的 register 函數部署後，它將在每次冷啟動時被呼叫（但在每個環境中僅呼叫一次）。

有時，由於檔案引入會產生的副作用，在程式碼中引入檔案可能很有用。例如，您可能引入一個定義了一組全域變數的檔案，但從未在程式碼中明確使用該引入的檔案。您仍然可以存取該套件宣告的全域變數。

您可以在 instrumentation.ts 中引入具有副作用的檔案，您可能希望在 register 函數中使用這些檔案，如下例所示：

import { init } from 'package-init'

export function register() {
  init()
}

不過，我們建議從 register 函數內部使用 import 來引入具有副作用的檔案。以下範例展示了在 register 函數中使用 import 的基本用法：

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

透過這種方式，您可以將所有副作用程式碼集中在一個位置，避免因引入檔案而產生意外的後果。

我們在所有環境中都會呼叫 register，因此有必要有條件地引入任何不支援 edge 和 nodejs 環境的程式碼。您可以使用環境變數 NEXT_RUNTIME 來取得當前環境。引入環境特定程式碼的範例如下：

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

  if (process.env.NEXT_RUNTIME === 'edge') {
    await import('./instrumentation-edge')
  }
}