SharePoint Online使用PnP PowerShell移动文件时如何获取作业进度

核心错误原因 #

• 原有脚本将Move-PnPFile移动命令和Receive-PnPCopyMoveJobStatus状态查询命令定义为了字符串变量，没有实际触发执行，因此不会产生任何操作效果
• 没有加入循环查询逻辑，仅执行单次状态判断，无法实现持续的进度监控

修正后可实现进度监控的完整脚本 #

#Config Variables
$SiteURL = "https://<site>.sharepoint.com/"
$SourceFolderURL= "sites/<site name>/<document library name>/<Folder or file location>"
$TargetFolderURL = "sites/<site name>/<document library name>"

#Connect to PnP Online
Connect-PnPOnline -Url $SiteURL -Interactive

# 触发移动任务返回任务对象，添加-Verbose可查看详细执行日志
$moveJob = Move-PnPFile -SourceUrl $SourceFolderURL -TargetUrl $TargetFolderURL -Overwrite -NoWait -Verbose

# 循环查询任务进度
do {
    Start-Sleep -Seconds 5 # 每5秒查询一次，可根据需求调整间隔
    $jobStatus = Receive-PnPCopyMoveJobStatus -Job $moveJob
    
    # 显示进度条与百分比
    if ($jobStatus.Total -gt 0) {
        $progressPercent = [math]::Round(($jobStatus.Processed / $jobStatus.Total) * 100, 2)
        Write-Progress -Activity "正在移动文件/文件夹" -Status "进度: $progressPercent% ($($jobStatus.Processed)/$($jobStatus.Total))" -PercentComplete $progressPercent
    } else {
        Write-Progress -Activity "正在移动文件/文件夹" -Status "正在初始化任务..."
    }

# 任务状态为3时代表仍在执行中，直到任务结束退出循环
} while ($jobStatus.JobState -eq 3)

# 任务结束后输出结果
Write-Progress -Activity "正在移动文件/文件夹" -Completed
switch ($jobStatus.JobState) {
    0 { Write-Host "✅ 任务执行成功，所有文件已完成移动" -ForegroundColor Green }
    1 { Write-Host "⚠️ 任务已被取消" -ForegroundColor Yellow }
    2 { Write-Host "❌ 任务执行失败，错误信息: $($jobStatus.Message)" -ForegroundColor Red }
}

功能说明 #

• 自动持续监控移动任务进度，无需手动刷新
• 实时展示移动百分比与已处理/总文件数，自带PowerShell进度条
• 支持-Verbose参数输出详细的执行日志，方便排查问题
• 任务结束后自动判断执行结果，输出对应提示

注意事项 #

• 若为跨站点移动操作，需要确保当前登录账号同时拥有源站点和目标站点的编辑权限
• 建议提前将PnP.PowerShell模块更新到最新版本，避免cmdlet兼容性异常
• 大文件/大量文件移动时可适当调大循环等待的秒数，减少不必要的API请求

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