Azure DevOps Linux自托管代理使用AzurePowerShell@5任务报错的解决方法

以下是针对Linux自托管代理的具体排查和解决步骤：

1. 确认模块安装状态与路径 #

在代理机器上以DevOps服务账户（或代理运行的用户）执行以下命令，验证Az模块是否正确安装：

Get-Module -ListAvailable Az

查看输出的Version是否为11.1.0，同时记录InstalledLocation的路径。如果模块不存在或版本不对，重新执行全局安装命令：

Install-Module -Name Az -RequiredVersion 11.1.0 -Scope AllUsers -Force -AllowClobber

2. 检查目录权限 #

确保DevOps代理的运行用户拥有模块安装路径的读取权限。比如模块安装在/usr/local/share/powershell/Modules/Az/11.1.0，执行：

sudo chmod -R 755 /usr/local/share/powershell/Modules/Az/11.1.0

如果代理用特定用户运行（如azdo），还需确保用户对该路径有访问权：

sudo chown -R azdo:azdo /usr/local/share/powershell/Modules/Az/11.1.0

3. 调整流水线任务配置 #

在AzurePowerShell@5任务中，确保以下配置正确：

• 设置azurePowerShellVersion为Specify exact version，并填入11.1.0
• 明确启用PowerShell Core，添加参数pwsh: true
• 示例任务YAML配置：

- task: AzurePowerShell@5
  inputs:
    azureSubscription: 'Your-Subscription'
    ScriptType: 'FilePath'
    ScriptPath: 'your-script.ps1'
    azurePowerShellVersion: 'Specify exact version'
    preferredAzurePowerShellVersion: '11.1.0'
    pwsh: true

4. 清理代理模块缓存 #

AzureDevOps代理会缓存Az模块，若缓存损坏可能导致版本检测失败。删除代理的模块缓存目录：

rm -rf $HOME/.azuredevops/azmodulecache/Az/11.1.0

之后重新运行流水线，任务会重新检测本地安装的模块。

5. 手动加载模块（临时 workaround） #

如果任务仍无法识别模块，可在脚本开头直接指定模块路径加载：

# 替换为实际的InstalledLocation路径
Import-Module -Path "/usr/local/share/powershell/Modules/Az/11.1.0/Az.psd1" -Force

6. 验证代理PowerShell环境 #

在流水线中添加一个PowerShell任务，先输出环境信息，确认PowerShell版本和模块状态：

- task: PowerShell@2
  inputs:
    targetType: 'inline'
    script: |
      $PSVersionTable
      Get-Module -ListAvailable Az

确保PSVersion在7.0及以上（Az 11.1.0的最低要求），且Az模块11.1.0存在。

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