檢測

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

慣例

若要設定檢測，請在專案的根目錄中（或在使用 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')
  }
}