使用PnPListItem处理SharePoint深层文件夹超5K文件阈值问题

问题背景 #

在SharePoint列表中存在一个6级深度的文件夹，包含超5000个文件需要拆分归档。使用Get-PnPFolderItem时触发**"The attempted operation is prohibited because it exceeds the list view threshold"**阈值错误。尝试用带-PageSize参数的Get-PnPListItem绕过限制，但遇到以下问题：

• Get-PnPListItem默认返回列表根目录，而非目标深层文件夹
• 使用-FolderServerRelativeUrl参数时，返回**"The query.FolderServerRelativeUrl argument is invalid"**错误
• 编写的CAML查询无法正确返回目标文件夹内容：要么仅返回列表根目录，要么仍触发阈值错误，部分查询无结果

测试代码 #

$SiteUrl = "https://mytenant.sharepoint.com/Maintenance"
$listname = "workshop"
$ServerRelUrl = "Maintenance/workshop/level1/level2/level3/level4/level5/level6"

Connect-PnPOnline -URL $siteUrl -credentials $cred

Get-PnPFolderItem $serverRelUrl  # 触发列表视图阈值错误

Get-PnPListItem -list $listname -FolderServerRelativeUrl $ServerRelUrl   # 返回"query.FolderServerRelativeUrl参数无效"错误
# 请问这个参数应该怎么填？

$query="<View Scope='RecursiveAll'><RowLimit>5000</RowLimit></View>"
Get-PnPListItem -list $listname -query $query       # 返回列表下所有文件和文件夹，分页后未触发阈值，符合预期

# Workshop TK001是文件名的一部分
$query='<view><Query><Where><Contains><FieldRef Name='FileDirRef'/></Contains></Where></Query></View>'
Get-PnPListItem -list $listname -query $query       # 无结果返回

$query="<Query> <Where> <Contains> <FieldRef Name='FileDirRef' /> <Value Type='File'>'workshop/level1/level2/level3/level4/level5'</Value> </Contains> </Where> </Query> <ViewFields /> <QueryOptions />"
Get-PnPListItem -list $listname -query $query       # 仅返回列表根文件夹

$query="<view Scope='RecursiveAll'><Query> <Where> <Contains> <FieldRef Name='FileDirRef' /> <Value Type='File'>'workshop/level1/level2/level3/level4/level5'</Value> </Contains> </Where> </Query> <ViewFields /> <QueryOptions /></view>"
Get-PnPListItem -list $listname -query $query       # 触发列表视图阈值错误
Get-PnPListItem -list $listname -query $query -PageSize 2000   # 仍触发阈值错误
Get-PnPListItem -list $listname -PageSize 2000 -query $query   # 仍触发阈值错误

问题原因分析 #

1. -FolderServerRelativeUrl参数格式错误：该参数需要完整的站点相对URL（开头必须带斜杠），而非从站点名称开始的路径。
2. CAML查询语法与逻辑错误：
   • FileDirRef字段匹配时，Value类型应为Text而非File；
   • 使用Contains匹配父文件夹路径时，会触发全表扫描，若结果集超过阈值，即使分页也会报错；
   • 部分查询存在字符串引号嵌套问题，导致无结果返回。
3. Get-PnPFolderItem局限性：该命令不支持分页，一次性获取大量内容时直接触发阈值限制。

可行解决方案 #

方案1：修正-FolderServerRelativeUrl参数并结合分页 #

使用正确格式的文件夹相对URL，配合分页参数绕过阈值：

$SiteUrl = "https://mytenant.sharepoint.com/Maintenance"
$listname = "workshop"
# 修正后的相对URL：开头带斜杠，为站点根到目标文件夹的完整路径
$ServerRelUrl = "/Maintenance/workshop/level1/level2/level3/level4/level5/level6"

Connect-PnPOnline -URL $siteUrl -Credentials $cred

# 分页获取目标文件夹下所有层级的内容（去掉-Recursive则仅返回当前文件夹内容）
$items = Get-PnPListItem -List $listname -FolderServerRelativeUrl $ServerRelUrl -PageSize 2000 -Recursive

方案2：基于FileRef的高效CAML查询 #

利用FileRef字段的索引特性，使用BeginsWith进行精确匹配，避免全表扫描：

$targetFolderPath = "/Maintenance/workshop/level1/level2/level3/level4/level5/level6"
$query = @"
<View Scope='RecursiveAll'>
    <Query>
        <Where>
            <BeginsWith>
                <FieldRef Name='FileRef' />
                <Value Type='Text'>$targetFolderPath</Value>
            </BeginsWith>
        </Where>
    </Query>
    <RowLimit>2000</RowLimit>
</View>
"@

$items = Get-PnPListItem -List $listname -Query $query -PageSize 2000

方案3：递归遍历子文件夹（分批次处理） #

逐个遍历每个子文件夹，确保单次获取的内容不超过阈值：

function Get-FolderItemsRecursively {
    param(
        [Parameter(Mandatory=$true)]
        [Microsoft.SharePoint.Client.Folder]$Folder,
        [int]$PageSize = 2000
    )
    # 获取当前文件夹内容
    $items = Get-PnPListItem -List $Folder.ParentList -FolderServerRelativeUrl $Folder.ServerRelativeUrl -PageSize $PageSize
    foreach ($item in $items) { $item }
    # 递归处理子文件夹
    $subFolders = Get-PnPFolderItem -Folder $Folder -ItemType Folder
    foreach ($subFolder in $subFolders) {
        Get-FolderItemsRecursively -Folder $subFolder -PageSize $PageSize
    }
}

# 获取目标文件夹对象
$targetFolder = Get-PnPFolder -Url $ServerRelUrl
# 递归获取所有内容
$allItems = Get-FolderItemsRecursively -Folder $targetFolder -PageSize 2000

关键注意事项 #

• 确保FileRef/FileDirRef字段已被索引（SharePoint默认索引，若未开启需手动在列表设置中配置）；
• PageSize建议设为2000，这是SharePoint允许的最大分页大小；
• 优先使用BeginsWith/Eq进行精确匹配，避免Contains引发的全表扫描。

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