排查 Azure Functions 中的 Node.js 应用问题

重要

本文的内容根据你在此页顶部的选择器中选择的 Node.js 编程模型而异。 v4 模型已正式发布，旨在为 JavaScript 和 TypeScript 开发人员提供更为灵活和直观的体验。在迁移指南中详细了解 v3 和 v4 之间的差异。

本文提供了 Node.js 函数应用中常见方案的故障排除指南。

Azure 门户中的“诊断和解决问题”选项卡是一种有用的资源，用于监视和诊断与应用程序相关的可能问题。它还根据诊断提供问题的潜在解决方案。

另一个有用的资源是 Application Insights 实例的 Azure 门户中的“日志”选项卡，以便可以运行自定义 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()，builder.AddServiceBus()，builder.AddTimers()，等）。

请尝试以下修复：

在本地运行时，请确保使用的是 Azure Functions Core Tools v4.0.5382 或更高版本。
在 Azure 中运行时：
- 请确保使用的是 Azure Functions 运行时版本 4.25 或更高版本。
- 请确保使用的是 Node.js v18 或更高版本。
- 将应用设置 FUNCTIONS_NODE_BLOCK_ON_ENTRY_POINT_ERROR 设置为 true. 建议对所有模型 v4 应用使用此设置，并确保所有入口点错误在 Application Insights 日志中可见。有关详细信息，请参阅 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/functions”包切换到测试模式 - 并非所有功能都受支持。

请检查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()。
检查你在函数定义前是否注册了钩子。
如果钩子应仅针对特定函数类型运行，请检查触发器过滤。

TypeScript编译问题

针对TypeScript特有的问题：

构建失败：

确认 tsconfig.json 具有指向你的构建输出的正确 outDir
确保在 v3 模型中，scriptFile 指向已编译的 .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 门户中函数应用页的“支持 + 故障排除”部分创建支持票证。

后续步骤

Last updated on 2026-08-14