Azure DevOps本地发布报“Ampersand not allowed”错误求排查方案

我之前帮团队排查过几乎一模一样的问题，虽然你已经排除了用户名、密码、机器名的问题，但这个错误的根源往往藏在远程会话执行的命令细节或者环境兼容性里。以下是几个亲测有效的排查方向：

1. 打印远程执行的完整命令，揪出隐藏的& #

Retry-Connection函数会构建远程PowerShell命令来验证会话状态，脚本里的&是语法符号，但如果远程执行的命令参数里悄悄混入了&（比如发布路径、环境变量），就会触发这个错误。

• 临时修改SessionHelper.ps1的Retry-Connection函数，在执行远程命令前加一行日志：

  Write-Verbose "Debug: Remote command to execute: $($command.ToString())" -Verbose
  

  然后重新触发发布，查看日志里的完整命令，就能一眼看到哪里藏了&。

2. 检查本地与远程机器的PowerShell版本差异 #

不同PowerShell版本对语法解析的严格程度不一样，尤其是5.1和7.x之间：

• 在本地代理机和目标机器上分别执行$PSVersionTable.PSVersion，确认版本是否一致。
• 如果目标机是旧版PowerShell，尝试在Azure DevOps发布任务里指定PowerShell版本（任务配置里有“PowerShell版本”选项），或者临时升级目标机的PowerShell到稳定版。

3. 排查Azure DevOps变量的隐藏转义字符 #

有时候你手动输入的变量看起来没问题，但Azure DevOps会自动转义某些字符（比如把&转成&，但解析时又变回&）：

• 进入发布管道的变量页，点击每个变量的“查看原始值”，确认没有隐藏的&或转义后的字符。
• 添加一个临时PowerShell步骤，输出所有相关变量：

  Write-Host "Deployment Path: $env:DeploymentPath"
  Write-Host "Agent Work Folder: $env:AGENT_WORKFOLDER"
  

  看看输出里有没有意外的&。

4. 验证远程会话的编码设置 #

字符编码不匹配可能导致正常字符被解析成&：

• 在SessionHelper.ps1中，确保传递给远程会话的字符串用UTF-8编码处理，比如：

  $encodedCommand = [Convert]::ToBase64String([System.Text.Encoding]::UTF8.GetBytes($command))
  

• 检查目标机器的系统区域设置，是否和代理机一致。

5. 临时修改脚本的&语法做测试 #

虽然用的是官方脚本，但可以临时把SessionHelper.ps1中173和176行的&改为字符串形式（'&'），测试是否还报错。如果问题消失，说明是远程会话的执行上下文对语法解析有特殊要求，这时候可以考虑提交issue给微软官方，或者保留这个临时修改（注意备份原脚本）。

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