SharePoint文档批量重命名Python脚本报错排查及优化需求

核心错误原因 #

你遇到的serverRelativeUrl参数错误，是因为get_file_by_server_relative_url()方法要求传入SharePoint服务器相对路径（而非完整的绝对URL）。你当前构造的file_url是完整的HTTPS开头地址，不符合接口参数要求。

修复后的完整脚本 #

以下脚本修正了路径问题，同时实现直接重命名（无需复制），并支持遍历目标文件夹及其子目录查找文件，适合大文件场景：

from office365.runtime.auth.authentication_context import AuthenticationContext
from office365.sharepoint.client_context import ClientContext
from office365.sharepoint.files.file import File
from office365.sharepoint.folders.folder import Folder
import pandas as pd
import os

sharepoint_url = "https://tenant.sharepoint.com/sites/siteName"
library_name = "DataToChange"  # Documents库下的目标子文件夹
local_excel_file_path = r"localExcelFilePath.xlsx"

def load_excel_data(excel_path):
    # 加载文件名映射表并转为字典，提升查找效率
    df = pd.read_excel(excel_path)
    return dict(zip(df['File Name'], df['NewFileName']))

def connect_to_sharepoint(sp_url, username, password):
    ctx_auth = AuthenticationContext(sp_url)
    if ctx_auth.acquire_token_for_user(username, password):
        return ClientContext(sp_url, ctx_auth)
    raise Exception(f"认证失败: {ctx_auth.get_last_error()}")

def find_file_recursive(folder: Folder, target_filename, name_mapping, ctx):
    # 递归遍历文件夹及子文件夹查找目标文件
    files = folder.files
    ctx.load(files)
    ctx.execute_query()
    
    for file in files:
        if file.name == target_filename:
            rename_sharepoint_file(file, name_mapping[target_filename], ctx)
            return
    
    # 遍历子文件夹
    sub_folders = folder.folders
    ctx.load(sub_folders)
    ctx.execute_query()
    for sub_folder in sub_folders:
        find_file_recursive(sub_folder, target_filename, name_mapping, ctx)

def rename_sharepoint_file(file: File, new_name, ctx):
    # 直接修改文件名，无复制操作
    try:
        # 未签出则先签出文件
        if not file.check_out_status:
            file.check_out()
            ctx.execute_query()
        
        # 处理SharePoint文件名长度限制（截断过长的文件名主体）
        name_no_ext, ext = os.path.splitext(new_name)
        name_no_ext = name_no_ext[:128]
        final_new_name = f"{name_no_ext}{ext}"
        
        # 更新文件名属性并提交
        file.set_property("Name", final_new_name)
        file.update()
        ctx.execute_query()
        
        # 签入文件（0=普通签入，2=覆盖签入，按需调整）
        file.check_in("Python脚本自动重命名", 0)
        ctx.execute_query()
        print(f"重命名成功: {file.name} -> {final_new_name}")
    except Exception as e:
        print(f"重命名失败 [{file.name}]: {str(e)}")
        # 异常时撤销签出，避免文件锁定
        if file.check_out_status:
            file.undo_check_out()
            ctx.execute_query()

if __name__ == "__main__":
    # 替换为你的SharePoint账号信息
    username = "your_username@tenant.com"
    password = "your_password"
    
    name_mapping = load_excel_data(local_excel_file_path)
    ctx = connect_to_sharepoint(sharepoint_url, username, password)
    
    # 获取Documents库根文件夹
    docs_root = ctx.web.lists.get_by_title("Documents").root_folder
    ctx.load(docs_root)
    ctx.execute_query()
    
    # 定位到目标子文件夹DataToChange
    target_folder = docs_root.folders.get_by_url(library_name)
    ctx.load(target_folder)
    ctx.execute_query()
    
    # 遍历所有需要重命名的文件
    for old_filename in name_mapping.keys():
        find_file_recursive(target_folder, old_filename, name_mapping, ctx)

关键改进点 #

• 路径错误修复：改用服务器相对路径查找文件，彻底解决serverRelativeUrl参数异常
• 无复制重命名：直接修改文件属性完成重命名，避免大文件复制的性能损耗
• 递归遍历支持：自动扫描目标文件夹的所有子目录，匹配需要重命名的文件
• 异常安全处理：添加签入/签出异常回滚逻辑，防止文件长期锁定
• 文件名合规处理：截断过长的文件名主体，适配SharePoint的命名限制

注意事项 #

1. 确保账号拥有目标文件的编辑+签入/签出权限
2. 若账号启用MFA（多因素认证），acquire_token_for_user方法会失效，需改用证书认证等MFA兼容方式
3. 建议先测试少量文件，确认重命名逻辑符合预期后再批量执行

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