Azure Pipelines自托管代理中az命令无法识别问题排查

核心原因：环境变量PATH缺失CLI路径 #

Azure CLI的az命令无法被识别，最常见的原因是Pipeline任务的运行环境中，系统环境变量PATH未包含Azure CLI的安装目录。即使你在本地管理员或NT AUTHORITY\NETWORK SERVICE用户的PowerShell中能正常运行，Pipeline代理服务启动时可能未加载最新的PATH配置，或者任务的上下文未继承完整的系统PATH。

快速验证与临时修复 #

在PowerShell任务开头手动添加Azure CLI的路径到当前环境的PATH中，再执行az命令：

# 根据实际安装位置调整路径，以下为默认路径示例
$cliInstallPath = "C:\Program Files (x86)\Microsoft SDKs\Azure\CLI2\wbin"
if (Test-Path $cliInstallPath) {
    $env:PATH += ";$cliInstallPath"
}
# 测试命令是否可识别
az --version

永久修复方案 #

1. 更新系统环境变量PATH：
   打开系统属性 → 高级 → 环境变量，在系统变量的Path中添加Azure CLI的wbin目录（通常为C:\Program Files (x86)\Microsoft SDKs\Azure\CLI2\wbin或C:\Program Files\Microsoft SDKs\Azure\CLI2\wbin）。
2. 重启Azure Pipelines代理服务：
   打开服务管理器，找到Azure Pipelines Agent服务并右键重启，让代理服务重新加载更新后的系统环境变量。

其他排查方向 #

• 确认代理服务运行用户：
  检查自托管代理服务的运行用户是否为NT AUTHORITY\NETWORK SERVICE（默认），如果是其他用户，需确保该用户的环境变量PATH包含CLI路径，优先推荐修改系统级PATH。
• 检查PowerShell任务模式：
  如果任务选择了PowerShell Core，需确认Azure CLI路径已添加到该环境的PATH中；Windows环境下优先使用Windows PowerShell任务模式，更适配Azure CLI的安装路径。
• 清理重复安装：
  你同时通过MSI和PowerShell Gallery安装了Azure CLI，可能导致路径冲突。建议保留MSI安装的系统级版本，卸载PowerShell Gallery的模块版本，避免环境混乱。

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