Node.js+TypeScript Azure Function App全路由404错误排查求助

1. 本地运行验证（先排除本地配置错误） #

• 检查host.json路由前缀配置：确保extensions.http.routePrefix未被错误设置，默认应为空字符串""，否则会导致路由前缀额外叠加，比如误设为api会让路由变成/api/api/{functionName}。

  {
    "extensions": {
      "http": {
        "routePrefix": ""
      }
    }
  }
  

• 核对local.settings.json核心配置：FUNCTIONS_WORKER_RUNTIME需匹配运行时（如node），本地开发时AzureWebJobsStorage可设为UseDevelopmentStorage=true。
• 验证函数注册逻辑：使用@azure/functions时，必须通过app.http()正确挂载函数，确保控制器/handler被注册到运行时。
  示例正确注册代码：

  import { app } from '@azure/functions';
  import { helloController } from './helloController';
  
  app.http('hello', {
    methods: ['GET', 'POST'],
    route: 'hello',
    handler: helloController,
  });
  

• 查看本地启动日志：启动后控制台会输出已注册的函数路由列表，如果没有显示你的函数，说明注册失败，重点排查代码语法错误、导出逻辑问题。

2. 代码规范检查（针对TypeScript/Node.js环境） #

• 确保handler签名符合要求：必须是异步函数，返回Promise<HttpResponse>，不能存在未处理的Promise拒绝。
  示例标准handler：

  import { HttpRequest, HttpResponse, HttpRequestContext } from '@azure/functions';
  
  export async function helloController(context: HttpRequestContext, req: HttpRequest): Promise<HttpResponse> {
    return {
      status: 200,
      body: 'Hello World',
    };
  }
  

• 检查文件命名与导出：Linux部署环境对文件名大小写敏感，确保控制器文件的引用路径、导出名称与注册代码一致，避免大小写不匹配。

3. 部署环节验证（针对GitHub Actions部署） #

• 检查部署脚本参数：确保azure/functions-action的app-name、slot-name与Azure函数应用信息一致，package指向正确的构建产物目录。
  示例部署步骤：

  - name: Deploy to Azure Functions
    uses: Azure/functions-action@v4
    with:
      app-name: your-function-app-name
      slot-name: production
      package: ./dist
      publish-profile: ${{ secrets.AZURE_FUNCTIONAPP_PUBLISH_PROFILE }}
  

• 部署后检查Azure Portal：如果Portal的函数列表中看不到你的函数，说明部署包无效，需确认TypeScript项目已编译为JS，package.json的main字段指向编译后的入口文件（如dist/index.js）。
• 核对函数应用设置：确保FUNCTIONS_EXTENSION_VERSION为最新稳定版，NODE_VERSION与本地开发环境一致。

4. 项目结构检查 #

• 遵循Azure Functions目录规范：根目录需包含host.json、local.settings.json、package.json，函数源码放在根目录或src文件夹，编译产物放在dist（TypeScript项目）。
  示例标准结构：

  your-function-app/
  ├── src/
  │   ├── index.ts
  │   └── helloController.ts
  ├── dist/
  │   ├── index.js
  │   └── helloController.js
  ├── host.json
  ├── local.settings.json
  └── package.json
  

• 避免过深的嵌套目录：Functions运行时默认仅扫描根目录及一级子目录的函数注册代码，过深嵌套会导致运行时无法识别函数。

内容的提问来源于stack exchange，提问作者Zein Rein