Azure DevOps中PowerShell映射驱动器成功却无法访问的解决问询

我想要在Azure DevOps中编写一个简单的YAML脚本，实现映射可被Azure访问的远程机器驱动器、在目标机器创建文件夹并复制文件的功能，后续还需执行更多代码任务，因此选择使用PowerShell实现。

我的YAML脚本片段如下：

...
stages:
- stage: CommonStage
  jobs:
  - job: CommonJob
    pool: 
      vmImage: 'windows-latest'
    steps:
    - checkout: none
    - task: PowerShell@2
      displayName: 'Create folder'
      inputs:
        targetType: 'inline'
        script: | 
          $mappedName = "z"
          $machine = "$(MachineIPAddress)"

          # Map the drive
          New-PSDrive -Verbose -Name $mappedName -PSProvider "FileSystem" -Root "\\$machine\c$\"

          # Set the location to the drive we _just_ mapped.
          z:
...

执行后，从输出可见驱动器已映射，但尝试切换到该驱动器时出现错误：

Name           Used (GB)     Free (GB) Provider      Root                                               CurrentLocation
----           ---------     --------- --------      ----                                               ---------------
z                                      FileSystem    \\aa.bb.cc.dd\c$\                                              

Set-Location : Cannot find path 'z:\' because it does not exist.
At line:1 char:1
+ Set-Location $MyInvocation.MyCommand.Name
+ ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
    + CategoryInfo          : ObjectNotFound: (z:\:String) [Set-Location], ItemNotFoundException
    + FullyQualifiedErrorId : PathNotFound,Microsoft.PowerShell.Commands.SetLocationCommand

同时执行Get-PSDrive能看到z驱动器已存在，但无法对其进行任何操作。

请问：为什么刚映射的驱动器路径找不到？若映射未成功为何无报错提示？如何在流水线中正确映射并使用该驱动器？

原因分析 #

1. PowerShell虚拟驱动器与系统驱动器的差异
   New-PSDrive创建的是PowerShell会话专属的虚拟驱动器，并非Windows系统级的映射驱动器。用z:这种方式切换时，系统会优先查找系统级映射的驱动器，而非PowerShell的虚拟驱动器，因此会提示路径不存在。

2. 未验证映射有效性
   New-PSDrive默认仅生成驱动器对象，不会立即校验远程路径的可访问性。哪怕远程机器不可达、权限不足或路径不存在，命令也不会报错，只会生成一个状态异常的虚拟驱动器，导致后续操作失败。

正确实现方案 #

方案1：直接使用UNC路径操作 #

跳过驱动器映射，直接通过UNC路径完成文件夹创建、文件复制等操作，规避会话级驱动器的限制：

$machine = "$(MachineIPAddress)"
$remotePath = "\\$machine\c$\target-folder"

# 创建远程文件夹
New-Item -Path $remotePath -ItemType Directory -Force

# 复制文件到远程路径
Copy-Item -Path "local-file-path" -Destination $remotePath -Recurse -Force

方案2：使用PowerShell虚拟驱动器并规范操作 #

如果必须使用驱动器号，需通过Set-Location明确指定PowerShell驱动器，或使用完整的虚拟驱动器路径：

$mappedName = "z"
$machine = "$(MachineIPAddress)"

# 创建全局作用域的虚拟驱动器，并验证路径可用性
$drive = New-PSDrive -Name $mappedName -PSProvider FileSystem -Root "\\$machine\c$\" -Scope Global
if (-not (Test-Path "$($drive.Name):\")) {
    throw "无法访问映射的驱动器 $($drive.Name):\"
}

# 方式A：通过完整路径切换位置
Set-Location -Path "$mappedName:\"

# 方式B：直接使用虚拟驱动器路径执行操作
New-Item -Path "$mappedName:\new-folder" -ItemType Directory -Force

方案3：映射系统级驱动器（需管理员权限） #

若需要创建系统级可见的驱动器，可使用net use命令替代New-PSDrive，这种映射在系统层面生效，支持z:方式切换：

$mappedName = "z:"
$machine = "$(MachineIPAddress)"
# 如需用户名密码，可添加 /user:domain\user password 参数，建议用Azure DevOps变量存储敏感信息
net use $mappedName "\\$machine\c$\" /persistent:no

# 验证映射是否成功
if ($LASTEXITCODE -ne 0) {
    throw "net use 映射驱动器失败"
}

# 切换驱动器并执行操作
Set-Location $mappedName
New-Item -Path ".\new-folder" -ItemType Directory -Force

额外注意事项 #

• 权限配置：确保Azure DevOps代理的服务账户拥有远程机器共享路径的访问权限，提前在远程机器上完成权限配置。
• 凭据管理：避免在脚本中明文写入密码，使用Azure DevOps变量组存储敏感凭据，通过$(CredentialVariable)引用。
• 错误处理：给New-PSDrive或net use添加错误处理参数（如-ErrorAction Stop），确保映射失败时立即抛出错误，便于排查问题。

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