含Add-PnPFolder的SharePoint2013 PowerShell脚本运行失败但命令行正常如何解决

核心故障原因分析 #

• 参数上下文不一致问题：独立PowerShell提示符和管理员身份运行的ISE，对传入参数的编码、大小写敏感度、路径解析规则存在差异，SharePoint的相对路径为大小写敏感，若$FolderRelativeURL参数的大小写、前后斜杠格式和实际站点路径不完全匹配，ISE运行时就会触发文件不存在错误，逐行手动执行时输入的路径格式正确，因此可以正常运行。
• 连接异步加载问题：Connect-PnPOnline使用-UseWebLogin参数时会触发交互式浏览器验证，ISE的脚本执行逻辑不会等待验证流程完全完成、站点上下文完全加载，就会继续执行下一行Get-PnPFolder命令，此时连接尚未生效，自然无法读取到目标路径；逐行执行时会人工等待验证完成再运行后续命令，上下文已经加载完成因此无报错。
• 管理员权限上下文隔离问题：以管理员身份启动的ISE会使用系统级的PowerShell执行上下文，和普通用户启动的PowerShell提示符的浏览器Cookie、站点缓存不共享，-UseWebLogin依赖的登录缓存在管理员上下文中未生效，会导致验证完成后实际权限不足，无法读取目标文件夹路径。
• 相对路径规则不匹配问题：Get-PnPFolder的-RelativeURL参数要求传入相对于当前站点根路径的相对路径，若传入的是相对于站点集根、或者相对于文档库的路径，部分运行环境下会解析失败。

排查解决思路 #

• 首先校验参数一致性：在Get-PnPFolder命令前插入调试代码Write-Host "传入路径：$FolderRelativeURL"，分别在ISE和普通PowerShell提示符中执行脚本，对比两次输出的路径大小写、斜杠格式是否完全一致，确保路径格式为文档库名/父文件夹路径，开头不要加多余的斜杠，比如Shared Documents/Project而非/Shared Documents/Project。
• 增加连接等待校验逻辑：在Connect-PnPOnline后添加上下文等待代码，确保站点连接完全生效后再执行后续操作，示例代码如下：

Connect-PnPOnline –Url $SiteUrl -UseWebLogin
# 等待站点上下文加载完成
do {
    Start-Sleep -Seconds 2
    $currentContext = Get-PnPContext
} while (-not $currentContext.Web.IsPropertyAvailable("ServerRelativeUrl"))

• 替换身份验证方式：优先放弃-UseWebLogin交互式验证，改用凭据验证避免Cookie上下文隔离问题，示例代码如下：

$siteCred = Get-Credential
Connect-PnPOnline -Url $SiteUrl -Credentials $siteCred

• 优化文件夹查询逻辑：增加父文件夹存在性校验，若父文件夹可能不存在提前补全创建逻辑，也可以改用Resolve-PnPFolder替代Get-PnPFolder，支持自动补全不存在的路径层级。
• 调整ISE运行配置：不要以管理员身份启动ISE，改用普通用户身份启动ISE后再执行脚本，执行前先运行Set-ExecutionPolicy RemoteSigned -Scope CurrentUser，确保执行权限和普通PowerShell提示符一致。

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