SharePoint Online超大列表批量签入文件的方法咨询

针对40万+文件的文档库批量签入需求，当前遇到的无CAML查询耗时极久、带RowLimit的CAML触发阈值错误问题，可通过以下几种方案解决：

方案一：为CheckoutUser字段添加索引，优化CAML分页查询 #

SharePoint Online的列表视图阈值（默认5000条）会在查询未索引字段时触发。CheckoutUser字段默认未建索引，这是导致阈值错误的核心原因。先给该字段添加索引，再结合分页查询即可绕过限制。

操作步骤： #

1. 进入文档库设置 → 列表设置 → 索引列 → 创建新索引，选择Checkout User字段完成添加。
2. 修改PowerShell代码，确保分页逻辑正确遍历所有结果：

$Result = @() # 结果数组
  
# 配置SPO站点URL
$SiteUrl = "https://contoso.sharepoint.com/sites/your-site"
  
# 文档库名称
$ListName = "Your-Doc-Library"
  
# 连接到SPO
Connect-PnPOnline -Url $SiteURL -Interactive
  
# 带分页的CAML查询，仅获取已签出文件
$CAMLQuery = @"
<View Scope='RecursiveAll'>
    <Query>
        <Where>
            <IsNotNull><FieldRef Name='CheckoutUser' /></IsNotNull>
        </Where>
    </Query>
    <RowLimit>5000</RowLimit> <!-- 使用阈值上限作为分页大小 -->
</View>
"@
   
# 分页获取所有已签出文件
$ListItems = @()
$currentPage = 1
do {
    $items = Get-PnPListItem -List $ListName -Query $CAMLQuery -PageSize 5000 -Page $currentPage
    if ($items.Count -eq 0) { break }
    $ListItems += $items
    $currentPage++
} while ($true)

$TotalFiles = $ListItems.Count
Write-Host "共找到 $TotalFiles 个已签出文件"
 
# 逐个签入文件
foreach ($item in $ListItems) {
    try {
        $file = Get-PnPFile -ListItem $item -AsFileObject
        Checkout-PnPFile -Url $file.ServerRelativeUrl # 确保文件处于签出状态（防止异常）
        Checkin-PnPFile -Url $file.ServerRelativeUrl -Comment "批量自动签入" -CheckinType MajorCheckIn
        $Result += [PSCustomObject]@{
            FileName = $file.Name
            Status = "签入成功"
        }
    } catch {
        $Result += [PSCustomObject]@{
            FileName = $item.FieldValues.FileLeafRef
            Status = "签入失败：$($_.Exception.Message)"
        }
    }
}

# 导出结果
$Result | Export-Csv -Path "批量签入结果.csv" -Encoding UTF8 -NoTypeInformation

方案二：按文件夹递归遍历，分批次处理 #

文档库中每个文件夹的内容是独立的，若单个文件夹下的文件数低于5000，可通过遍历所有文件夹，逐个处理文件夹内的已签出文件，完全避开阈值限制。

代码示例： #

$Result = @()
$SiteUrl = "https://contoso.sharepoint.com/sites/your-site"
$ListName = "Your-Doc-Library"

Connect-PnPOnline -Url $SiteURL -Interactive

# 递归遍历所有文件夹的函数
function Process-Folder($FolderUrl) {
    Write-Host "正在处理文件夹：$FolderUrl"
    # 获取当前文件夹下的已签出文件
    $items = Get-PnPListItem -List $ListName -FolderServerRelativeUrl $FolderUrl -Query @"
<View>
    <Query>
        <Where>
            <IsNotNull><FieldRef Name='CheckoutUser' /></IsNotNull>
        </Where>
    </Query>
</View>
"@
    # 处理当前文件夹的文件
    foreach ($item in $items) {
        try {
            $fileUrl = $item.FieldValues.FileRef
            Checkin-PnPFile -Url $fileUrl -Comment "批量自动签入" -CheckinType MajorCheckIn
            $Result += [PSCustomObject]@{
                FileName = $item.FieldValues.FileLeafRef
                Folder = $FolderUrl
                Status = "成功"
            }
        } catch {
            $Result += [PSCustomObject]@{
                FileName = $item.FieldValues.FileLeafRef
                Folder = $FolderUrl
                Status = "失败：$($_.Exception.Message)"
            }
        }
    }
    # 递归处理子文件夹
    $subFolders = Get-PnPFolderItem -FolderSiteRelativeUrl $FolderUrl -ItemType Folder
    foreach ($subFolder in $subFolders) {
        Process-Folder -FolderUrl $subFolder.ServerRelativeUrl
    }
}

# 从根文件夹开始处理
Process-Folder -FolderUrl "/sites/your-site/$ListName"

# 导出结果
$Result | Export-Csv -Path "按文件夹签入结果.csv" -Encoding UTF8 -NoTypeInformation

方案三：使用PnP批量操作（Batch）提升效率 #

针对大量文件的签入操作，使用PnP的批量操作可以减少HTTP请求次数，大幅提升处理速度，同时避免频繁请求导致的限制。

代码示例： #

$SiteUrl = "https://contoso.sharepoint.com/sites/your-site"
$ListName = "Your-Doc-Library"

Connect-PnPOnline -Url $SiteURL -Interactive

# 创建批量操作对象
$batch = New-PnPBatch

# 分页获取已签出文件（需先给CheckoutUser加索引）
$CAMLQuery = @"
<View Scope='RecursiveAll'>
    <Query>
        <Where>
            <IsNotNull><FieldRef Name='CheckoutUser' /></IsNotNull>
        </Where>
    </Query>
    <RowLimit>5000</RowLimit>
</View>
"@

$currentPage = 1
do {
    $items = Get-PnPListItem -List $ListName -Query $CAMLQuery -PageSize 5000 -Page $currentPage
    if ($items.Count -eq 0) { break }
    # 将签入操作加入批量
    foreach ($item in $items) {
        $fileUrl = $item.FieldValues.FileRef
        Checkin-PnPFile -Url $fileUrl -Comment "批量签入" -CheckinType MajorCheckIn -Batch $batch
    }
    # 提交当前批次
    Invoke-PnPBatch -Batch $batch
    # 重置批次对象
    $batch = New-PnPBatch
    $currentPage++
} while ($true)

Write-Host "批量签入操作完成"

注意事项 #

• 索引字段添加后需等待SPO后台生效（通常数分钟到数小时），再执行查询。
• 批量操作时建议控制每批次的操作数量（不超过5000），避免触发请求限制。
• 若文档库有大量嵌套文件夹，方案二的递归遍历可能耗时较长，但稳定性最高。

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