Windows环境使用shutil.copy覆盖目标文件时抛出SameFileError问题

核心触发逻辑 #

shutil.SameFileError的触发不依赖路径字面量是否相同，而是调用os.path.samefile()判断两个路径指向的实际文件实体是否一致，Windows和Unix下该函数的实现逻辑存在差异，因此会出现跨平台表现不一致的情况。

具体可能原因 #

• 路径转义错误
  你提供的报错信息中目标路径为 D:\\Project_Folder\\code_name\file1.png，注意code_name后的\f属于Python转义字符（对应ASCII换页符），如果构造路径时没有使用原始字符串（r""前缀）、也没有用os.path.join/pathlib等标准工具拼接路径，会导致路径解析结果和预期不一致，极大概率最终指向的路径和源文件路径相同。
• 目录重解析点关联
  Windows下的目录联接（Junction Point）、符号链接（Symlink）都属于重解析点，os.path.samefile()默认会解析重解析点的真实指向：如果company_name和code_name两个目录其中一个是另一个的链接，或者二者都指向同一个第三方目录，哪怕路径字面量不同，最终解析到的文件实体也是同一个，就会触发报错。你可以在CMD中执行dir /al D:\Project_Folder查看两个目录的属性确认是否为链接类型。
• 同步工具重定向
  如果Project_Folder属于OneDrive、坚果云等同步工具的管理目录，这类工具为了实现按需同步，会把本地文件映射到统一的缓存目录，通过重解析点实现路径伪装，也会导致os.path.samefile()判断两个路径指向同一文件。
• 旧版本Python Bug
  Python 3.8之前的版本，Windows平台的os.path.samefile()实现存在已知缺陷，会对包含特殊字符、长路径的文件产生误判。

验证&修复方案 #

1. 先打印验证路径解析结果：

print("源路径实际值：", str(file))
print("目标路径实际值：", destination_file)
print("系统是否判定为同一文件：", os.path.samefile(str(file), destination_file))

2. 路径构造统一使用pathlib或者os.path.join，避免硬编码字符串的转义问题：

# 正确示例
from pathlib import Path
src_path = Path("D:/Project_Folder/company_name/file1.png")
dst_path = Path("D:/Project_Folder/code_name/file1.png")
shutil.copy(src_path, dst_path)

3. 如果确认是重解析点导致的误判，可添加follow_symlinks=False参数跳过链接解析：

shutil.copy(str(file), destination_file, follow_symlinks=False)

4. 如果是目标文件已存在的场景，可以先删除目标文件再执行复制：

import os
if os.path.exists(destination_file):
    os.remove(destination_file)
shutil.copy(str(file), destination_file)

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