儀器化 (Instrumentation)

儀器化 (Instrumentation) 是使用程式碼將監控和記錄工具整合到應用程式中的過程。這讓您可以追蹤應用程式的效能和行為，並在生產環境中除錯問題。

慣例

要設定儀器化，請在專案的根目錄中建立 instrumentation.ts|js 檔案（如果使用 src 資料夾，則放在該資料夾內）。

然後，在檔案中匯出一個 register 函式。此函式將在啟動新的 Next.js 伺服器實例時被呼叫一次。

例如，要搭配 OpenTelemetry 和 @vercel/otel 使用 Next.js：

import { registerOTel } from '@vercel/otel'

export function register() {
  registerOTel('next-app')
}

請參閱 Next.js 與 OpenTelemetry 範例 以查看完整實作。

須知事項

• 此功能為實驗性。要使用它，您必須在 next.config.js 中明確啟用 experimental.instrumentationHook = true;。
• instrumentation 檔案應位於專案的根目錄，而不是 app 或 pages 目錄內。如果您使用 src 資料夾，則將檔案放在 src 內與 pages 和 app 同層的位置。
• 如果您使用 pageExtensions 設定選項 來新增副檔名，則也需要更新 instrumentation 的檔名以符合。

範例

匯入具有副作用的檔案

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

我們建議在 register 函式中使用 JavaScript import 語法來匯入檔案。以下範例展示了在 register 函式中使用 import 的基本用法：

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

須知事項：

我們建議從 register 函式中匯入檔案，而不是在檔案頂部匯入。這樣做可以將所有副作用集中在程式碼中的一個位置，避免因在檔案頂部全域匯入而產生意外的後果。

匯入執行環境特定的程式碼

Next.js 在所有環境中都會呼叫 register，因此有條件地匯入不支援特定執行環境（例如 Edge 或 Node.js）的程式碼非常重要。您可以使用 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')
  }
}