覆盖SharePoint库文件时如何不丢失原有版本历史？

此前测试方法失效原因 #

• context.Site.CreateCopyJobsAsync：该接口的版本保留能力仅针对复制源文件的版本到新位置，不支持覆盖已有文件时保留目标文件原有版本链。默认配置下作业只会复制源文件最新版本，即使开启版本复制参数，也会在覆盖目标文件时重置目标文件的唯一标识，导致原有版本关联断裂。
• IFile.MoveToAsync：该接口属于文件迁移操作，目标路径存在同名文件时，默认逻辑为删除原有目标文件实体、将源文件移动到目标位置，原有目标文件绑定的版本历史会随实体删除被清空，无法保留。

推荐实现方案（无额外权限要求，兼容所有SharePoint Online版本） #

核心逻辑：不替换文件实体，仅更新目标文件的二进制内容。SharePoint的文件版本历史是绑定到文件唯一UID的，只要不删除重建文件实体，仅更新内容的操作会自动保留所有历史版本，本次更新会作为新版本追加到版本链中，完全符合原生版本管理规则。
基于PnP.Core的实现代码：

// 按服务器相对路径获取待覆盖的目标文件
var targetFile = await context.Web.GetFileByServerRelativeUrlAsync("/sites/你的站点名称/文档库名称/目标文件路径.docx");
// 读取待上传的新文件内容流
await using var fileContentStream = File.OpenRead("本地待上传的新文件完整路径.docx");
// 执行内容覆盖，第二个参数必须传true，代表覆盖现有文件内容而非创建新文件
await targetFile.UploadAsync(fileContentStream, true);

操作前置要求：目标文档库已开启版本控制功能。操作完成后直接查看文件版本历史，可看到所有原有版本的创建人、创建时间、版本备注均完整保留，本次内容更新会作为最新版本存在。

特殊场景：需要同时保留目标文件旧版本+源文件版本链 #

如果需求是覆盖后版本历史里同时存在目标文件原有版本、以及源文件的所有历史版本，不要使用复制/移动类接口，按以下步骤操作：

• 先导出源文件的所有历史版本，按版本生成时间从早到晚排序，记录每个版本的备注、创建人信息
• 对目标文件执行签出操作，按时间顺序依次上传每个源文件历史版本的内容流，每次签入时填写对应版本的原始备注
• 最后上传源文件最新版本作为当前公开版本

该方案需要文档库编辑权限，操作生成的所有版本会占用租户版本存储配额，仅适合有明确版本合并需求的场景。

避坑说明 #

任何触发文件实体删除重建的操作（包括同名文件上传后删除旧文件、移动覆盖、复制作业覆盖）都会导致原有版本历史丢失，这类操作会变更文件的唯一UID，版本和文件的绑定关系会直接断裂，没有恢复可能。

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