使用PowerShell复制本地文件夹到SharePoint时出错求助

核心现象拆解 #

• 部分文档未完成复制
• 几秒后自动为每个文件创建同名文件夹
• 三类报错：Add-PnPFile提示"数据不可用，查询可能未执行"、"文件/文件夹已存在"，以及"迁移失败：参数超出有效范围"

逐类错误排查与修复 #

1. "文件/文件夹已存在" + 自动创建文件夹 #

这个问题本质是脚本逻辑混淆了文件与文件夹的处理流程：

• 遍历本地目录时，误将文件路径当作文件夹路径调用New-PnPFolder
• 上传文件前未验证目标路径是文件夹，导致把文件名当成了文件夹名创建
• 修复建议：
  • 严格拆分文件与文件夹的处理逻辑，用Get-ChildItem -File和Get-ChildItem -Directory分别遍历
  • 上传文件前先确保目标文件夹存在，避免路径拼接错误：

    $localFile = Get-Item "C:\LocalDocs\file.pdf"
    $targetFolderUrl = "/sites/CustomerSite/DocLib/TargetFolder"
    # 先验证并创建目标文件夹
    if (-not (Get-PnPFolder -Url $targetFolderUrl -ErrorAction SilentlyContinue)) {
        New-PnPFolder -Name "TargetFolder" -Folder "/sites/CustomerSite/DocLib"
    }
    # 再执行文件上传
    Add-PnPFile -Path $localFile.FullName -Folder $targetFolderUrl
    

2. "数据不可用，查询可能未执行" #

这类错误和PnP连接稳定性、请求频率过高有关：

• 批量操作时请求过于密集，触发SharePoint限流或连接池耗尽
• 长时间保持单个连接导致会话失效
• 修复建议：
  • 添加请求延迟与重试机制，避免频繁请求：

    $retryCount = 3
    for ($i=1; $i -le $retryCount; $i++) {
        try {
            Add-PnPFile -Path $localFile.FullName -Folder $targetFolderUrl -ErrorAction Stop
            break
        }
        catch {
            if ($i -eq $retryCount) { throw $_ }
            Start-Sleep -Seconds $i
        }
    }
    

  • 每个客户站点操作完成后重新建立PnP连接，避免会话超时

3. "迁移失败：参数超出有效范围" #

该错误源于参数不符合SharePoint规则：

• 文件名/路径包含非法字符（如#、%、&、*等）
• 文件大小超出站点上传限制（默认15GB，部分租户可能调整）
• 修复建议：
  • 批量上传前清理文件名非法字符：

    $invalidChars = [System.IO.Path]::GetInvalidFileNameChars() + @('#', '%', '&', '*', '?')
    $cleanFileName = $localFile.Name
    foreach ($char in $invalidChars) {
        $cleanFileName = $cleanFileName.Replace($char, '_')
    }
    

  • 检查文件大小，跳过超出限制的文件，或联系管理员调整站点上传配额

性能优化建议（兼顾速度与稳定性） #

• 放弃PowerShell Job，改用Start-ThreadJob（轻量级线程）控制并发数（建议≤5），避免触发SharePoint并发限制
• 按客户站点分组处理本地文件，减少跨站点连接切换的开销
• 使用PnP批量操作模式，减少HTTP请求次数：

  $batch = New-PnPBatch
  foreach ($file in $localFiles) {
      Add-PnPFile -Path $file.FullName -Folder $targetFolderUrl -Batch $batch
  }
  Invoke-PnPBatch -Batch $batch
  

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