檢測

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

慣例

若要設定檢測，請在專案的根目錄中 (或在使用 src 資料夾的情況下在其內部) 建立 instrumentation.ts|js 檔案。

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

例如，若要將 Next.js 與 OpenTelemetry 和 @vercel/otel

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 的基本用法

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