VS Code本地运行Azure Functions遇500错误，求排查调试方案

500错误常见原因 #

• 依赖包安装不完整或版本冲突：npm install未执行完成，或@azure/functions等核心包版本与Runtime不兼容
• Azure Functions Core Tools版本不匹配：本地Core Tools版本与项目指定的Functions Runtime（如v3）不兼容
• 配置文件错误：
  • local.settings.json缺少必要配置（如AzureWebJobsStorage、FUNCTIONS_WORKER_RUNTIME）或配置值无效
  • function.json中触发器参数配置错误（如HTTP触发器的authLevel、路径设置）
• TypeScript编译异常：tsconfig.json配置错误（如目标JS版本、输出路径），导致编译后的代码无法被Functions宿主识别
• 端口占用：默认运行端口7071被其他进程占用，导致服务启动失败

本地运行排查与解决步骤 #

• 重新安装依赖并编译：
  在项目根目录执行：

  npm install
  npm run build
  

  查看编译过程中的报错，修复TypeScript语法或配置问题
• 检查Core Tools版本：
  执行func --version，确认版本与项目Runtime匹配（v3项目需Core Tools 3.x+），版本不兼容则卸载后重新安装对应版本
• 修正配置文件：
  • local.settings.json：确保FUNCTIONS_WORKER_RUNTIME设为node；若使用非HTTP触发器，需设置AzureWebJobsStorage为UseDevelopmentStorage=true（需启动Azurite模拟器）
  • function.json：核对触发器配置参数，比如HTTP触发器的route、methods是否符合预期
• 释放占用端口：
  Windows执行：

  netstat -ano | findstr :7071
  taskkill /F /PID <进程ID>
  

  Mac/Linux执行：

  lsof -i :7071
  kill -9 <进程ID>
  

• 查看详细日志：忽略VS Code右下角提示，直接查看终端中Functions Core Tools输出的日志，里面会包含500错误的具体堆栈信息

本地测试方案 #

• HTTP触发器测试：
  用curl或Postman访问http://localhost:7071/api/<函数名>，传递请求参数验证返回结果；也可在VS Code的Azure Functions扩展中右键函数，选择「Execute Function Now」快速测试
• 非HTTP触发器测试：
  比如Timer触发器，启动Azurite模拟器后启动函数，查看终端日志确认函数是否按时触发；Queue触发器可手动向本地存储队列添加消息，验证函数是否处理
• 单元测试：
  将函数的业务逻辑抽离为独立模块，用Jest/Mocha编写单元测试，直接测试模块功能，无需启动Functions宿主服务

本地调试方案 #

• 确认VS Code调试配置：
  项目.vscode/launch.json需包含正确的调试配置：

  {
    "version": "0.2.0",
    "configurations": [
      {
        "name": "Attach to Node Functions",
        "type": "node",
        "request": "attach",
        "port": 9229,
        "preLaunchTask": "func: host start"
      }
    ]
  }
  

• 启动调试流程：
  先执行npm run build编译代码，点击VS Code调试按钮启动调试；在TypeScript代码中设置断点，触发函数（如访问HTTP路径）即可命中断点，查看变量、调用栈信息
• 调试无响应排查：
  若断点未命中，检查启动命令是否开启调试端口，可手动执行func start --inspect，确保调试端口9229正常监听

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