问题描述

在本地调试 PowerShell Functions 项目时，有两类错误经常出现，堪称开发过程中的“拦路虎”：运行时加载失败和认证失败。当按下 F5 或执行 func start 后，终端直接抛出 Unable to find type [HttpResponseContext]；同样的代码部署到 Azure 上可以正常运行，本地却找不到该类型。另一类问题是认证失败：项目在云端使用 User-assigned Managed Identity 连接 Microsoft Graph，本地运行时却报 Could not acquire access to file at '.mgmg.context.json'，导致 Function 无法启动。

这两类错误的根源都不在代码本身，而是本地环境配置不足——更直接地说，本地环境无法模拟 Azure 的 Managed Identity 机制。

问题解答

一：解决加载失败错误：Unable to find type [HttpResponseContext]

问题的根本原因很简单：本地 PowerShell Worker 未正确加载 Azure Functions 内置模块。排查顺序其实不复杂，按步骤操作即可。

1. 检查 PowerShell 版本

Azure Functions v4 要求使用 PowerShell 7.x，Windows 系统自带的 5.x 不兼容。可通过 $PSVersionTable.PSVersion 快速确认版本。如果是 5.x，需要单独安装 PowerShell 7——它可与系统自带的 Windows PowerShell 5 共存，不会产生冲突。

2. 确认 VS Code 终端指向 PowerShell 7

按下 Ctrl + Shift + P，输入 Terminal: Select Default Profile，然后选择“PowerShell 7”（名称可能显示为 pwsh）即可。

3. 确认 local.settings.json 中的配置

确保 local.settings.json 中 FUNCTIONS_WORKER_RUNTIME 明确设置为 powershell，并补充一条关键配置："powershell.defaultProfile": "PowerShell 7"。一份完整的配置文件示例如下：

{
  "IsEncrypted": false,
  "Values": {
    "AzureWebJobsStorage": "UseDevelopmentStorage=true",
    "FUNCTIONS_WORKER_RUNTIME": "powershell",
    "powershell.defaultProfile": "PowerShell 7"
  }
}

此字段若未设置或填写错误，本地运行时会加载默认 Worker，导致 HttpResponseContext 等 PowerShell 内置类型完全无法识别——这恰恰是此类报错最常见、最直接的原因。

二：解决认证失败问题：User-assigned Managed Identity 本地认证不支持

Managed Identity 是 Azure 托管环境专用的认证机制，本地机器上不存在 MSI endpoint，因此无法模拟。在本机运行使用 UMI 的 Function 时，出现 Could not acquire access to file at '.mgmg.context.json' 是必然结果。

本地开发时，以下三种替代方案可供选择：

方案一：使用 Service Principal + Client Secret（推荐，行为最接近云端）

在 local.settings.json 中添加以下三个环境变量：

"AZURE_CLIENT_ID": "",
"AZURE_CLIENT_SECRET": "",
"AZURE_TENANT_ID": ""

脚本中改用以下方式连接 Microsoft Graph：

Connect-MgGraph -ClientId $env:AZURE_CLIENT_ID `
                -TenantId $env:AZURE_TENANT_ID `
                -ClientSecretCredential (
                    [System.Net.NetworkCredential]::new("", $env:AZURE_CLIENT_SECRET).SecurePassword
                )

方案二：交互式登录（适合临时本地调试，不适合 CI）

Connect-MgGraph -Scopes "User.Read.All","Group.Read.All"

方案三：环境变量条件判断（让同一份代码兼容本地和云端）

if ($env:MSI_ENDPOINT) {
    # 云端：使用 User-assigned Managed Identity
    Connect-MgGraph -Identity -ClientId $env:UMI_CLIENT_ID
} else {
    # 本地：使用 Service Principal
    Connect-MgGraph -ClientId $env:AZURE_CLIENT_ID -TenantId $env:AZURE_TENANT_ID `
                    -ClientSecretCredential (...)
}

方案三的优势明显——无需修改业务代码，即可在本地和 Azure 之间无缝切换。

参考资料

使用 Core Tools 在本地开发 Azure Functions：https://learn.microsoft.com/zh-cn/azure/azure-functions/functions-run-local?tabs=windows,isolated-process,node-v4,python-v2,http-trigger,container-apps&pivots=programming-language-powershell