在Azure Functions中排除 Node.js 應用程式的問題

Important

本文的內容會根據您在頁面頂端選取器中選擇的 Node.js 程式設計模型而有所不同。 v4 模型已正式推出，旨在為 JavaScript 和 TypeScript 開發人員提供更靈活且更直覺的體驗。 在移轉指南中深入了解 v3 與 v4 之間的差異。

本文提供了一套針對 Node.js 函式應用程式常見情境的故障排除指南。

Azure 入口網站中的「診斷與解決問題」分頁是監控與診斷與應用程式相關問題的實用資源。 它也會根據診斷，為您的問題提供潛在的解決方案。 更多資訊請參見 Azure 功能應用程式診斷。

另一個有用的資源是 Azure 入口網站的 Logs 標籤，針對你的 Application Insights 實例，這樣你可以執行自訂的 KQL 查詢。 以下範例查詢展示了如何檢視過去一天應用程式的錯誤與警告：

let myAppName = "<your app name>";
let startTime = ago(1d);
let endTime = now();
union traces,requests,exceptions
| where cloud_RoleName =~ myAppName
| where timestamp between (startTime .. endTime)
| where severityLevel > 2

如果這些資源無法解決你的問題，以下章節將針對特定申請問題提供建議：

未發現函數

如果你在日誌中看到以下任何錯誤：

找不到任何 HTTP 觸發器。

找不到職務功能。 試著讓你的工作課程和方法公開。 如果你使用綁定擴充功能（例如 Azure 儲存體、ServiceBus、Timers 等），請確保你在啟動程式碼中呼叫了擴充功能的註冊方法（例如 builder。AddAzureStorage（）， 建構器。AddServiceBus（）， 建構器。AddTimers（），等等）。

試試以下修正方法：

  • 本地執行時，請確保你使用的是 Azure Functions Core Tools v4.0.5382 或更高版本。
  • 在 Azure 中運行時：

    • 請確保你使用的是 Azure Functions Runtime 版本 4.25 或更高版本。

    • 務必使用 Node.js v18或更高。

    • 將應用程式設定 FUNCTIONS_NODE_BLOCK_ON_ENTRY_POINT_ERROR 設為 true。 此設定建議適用於所有 v4 型號應用程式，並確保所有入口錯誤都能在您的應用程式洞察日誌中顯示。 如需詳細資訊，請參閱 Azure Functions 的應用程式設定參考。

    • 檢查你的函式應用程式記錄中是否有進入點錯誤。 以下範例查詢說明如何檢視過去一天應用程式的入口錯誤：

      let myAppName = "<your app name>";
let startTime = ago(1d);
let endTime = now();
union traces,requests,exceptions
| where cloud_RoleName =~ myAppName
| where timestamp between (startTime .. endTime)
| where severityLevel > 2
| where message has "entry point"
  • 確保你的應用程式有 所需的資料夾結構 ，根目錄有 host.json ，每個函式都有一個包含 function.json 檔案的資料夾。

Undici 請求不是建構函件

如果你在功能應用程式日誌中出現以下錯誤：

System.Private.CoreLib：執行函式時發生異常：Functions.httpTrigger1。 System.Private.CoreLib： 結果：失敗 例外：undici_1.Request 不是建構子

請確定你使用的是 22.x 或更高版本 Node.js。

無法偵測 Azure Functions 執行階段

如果你在功能應用程式日誌中出現以下錯誤：

警告：未能偵測到 Azure Functions 執行時。 將「@azure/功能」套件切換到測試模式——並非所有功能都被支援。

檢查你的 package.json 檔案是否有參考資料 applicationinsights ，並確保版本是 ^2.7.1 或更高。 更新版本後，請執行 npm install

HTTP 串流無法運作

如果 HTTP 串流無法運作：

  • 請確認 @azure/functions 套件版本為 4.3.0 或更新版本。
  • 確保 Azure Functions 運行時版本係 4.28 或更後版本。
  • 檢查是否已呼叫 app.setup({ enableHttpStream: true })。
  • Verify FUNCTIONS_REQUEST_BODY_SIZE_LIMIT 是針對大型資料設定的。

勾點未執行

如果您的勾點未執行：

  • 確認你使用的是程式模型 v4。
  • 驗證掛鉤註冊語法： app.hook.preInvocation() 或 app.hook.appStart()。
  • 檢查你在函式定義前是否註冊了掛鉤。
  • 如果 Hook 只應針對特定函式類型執行，請檢查觸發條件篩選。

TypeScript 編譯問題

針對 TypeScript 特定問題：

建造失敗：

  • 確認 tsconfig.json 具有正確的 outDir，並指向您的建置輸出
  • 確保 scriptFile v3 中模型指向已編譯的 .js 檔案，而不是 .ts
  • 檢查所有 TypeScript 相依套件是否已安裝： npm install --save-dev typescript @types/node

類型錯誤：

  • 更新 @azure/functions 套件以支援最新型別定義
  • 使用正確的匯入： import { app, HttpRequest, InvocationContext } from '@azure/functions'
  • 驗證函式簽名是否符合預期類型

模組解析問題

找不到模組錯誤：

  • 執行 npm install 以確保所有相依性都已安裝
  • 檢查部署套件中是否存在 node_modules 資料夾
  • 對於 ES 模組，請確保檔案名稱使用 .mjs 副檔名，或在 package.json 中包含 "type": "module"
  • 在 TypeScript 編譯後，確認相對匯入路徑是否正確

環境與設定問題

缺少環境變數：

  • 加入變數 local.settings.json 以促進局部發展
  • 在 Azure 入口網站中設定用於雲端部署的應用程式設定
  • 使用 process.env["VARIABLE_NAME"] 來存取值

記錄問題：

  • 函式專用記錄請使用 context.log()，不要使用 console.log()
  • 檢查是否已設定 Application Insights 的連接字串
  • 確認 host.json 中用於篩選的記錄層級

尋求 Microsoft 的協助

你可以透過以下方式之一獲得 Microsoft 的更多協助：

  • 在Azure Functions Node.js庫中搜尋已知問題。 如果你沒看到有人提到你的問題，請建立一個新問題並告訴我們發生了什麼事。
  • 如果你無法透過本指南診斷問題，Microsoft 支援工程師隨時準備協助診斷你的應用程式問題。 Microsoft 提供多種支援方案。 在 Azure 入口網站功能應用程式頁面的支援+故障排除區建立支援工單。

下一步

  • 上次更新時間：