网络驱动器源文件夹下shutil.copytree执行失败问题排查

问题背景 #

• 环境：两地开发者均使用Windows 10系统 + Python 3.7.9版本
• 存储配置：
  • Y:盘为本地挂载的网络驱动器，两地无法互访
  • \\domain_name\code为DFS同步路径，用于跨地点代码发布同步
• 操作流程：开发者先在Y:盘打包版本包，再通过shutil.copytree复制到DFS路径；A地操作完全正常，B地失败率极高

错误现象 #

• 典型报错：

  shutil.Error: [('Y:\package\src\file.py', '\\domain\code\package\src\file.py', "[Errno 2] No such file or directory: 'Y:\package\src\file.py\file.py'")]
  

• 错误特征：程序错误地将文件路径（如Y:\package\src\file.py）当作目录，再拼接文件名形成无效路径Y:\package\src\file.py\file.py
• 复现特性：
  • 运行示例代码可稳定复现：

    import shutil
    src = r'Y:\package'
    dst = r'\\domain\code\package'
    shutil.copytree(src, dst)
    

  • 附加调试器时错误从未出现，推测存在竞态条件
  • 重试操作通常可成功，偶尔Y:盘内部复制也会触发相同错误

排查思路 #

1. 网络文件系统元数据读取异常排查 #

• 在复制流程中添加日志，记录关键路径处理的返回值：
  • 对每个待复制的文件/目录，打印os.path.isfile()、os.path.isdir()、os.path.basename()的结果，重点关注报错文件的这些值是否出现异常（比如文件被误判为目录）
  • 验证Python 3.7.9对UNC路径（DFS属于UNC路径）的处理是否存在已知bug，可核对Python官方issue中同类网络路径下的os.path方法异常案例

2. 竞态条件验证与规避 #

• 尝试在复制操作中添加短暂延迟（如每个文件复制前sleep(0.1)），观察错误率是否下降，验证竞态条件的存在
• 检查B地DFS节点的同步状态：确认DFS本地节点的元数据更新是否存在延迟，是否因文件系统响应不及时导致路径判断错误

3. 替换shutil.copytree实现，绕过潜在bug #

• 自行实现可控的目录复制逻辑，避免原shutil内部的路径拼接问题，示例代码：

  import os
  import shutil
  
  def custom_copytree(src, dst):
      os.makedirs(dst, exist_ok=True)
      for root, dirs, files in os.walk(src):
          rel_path = os.path.relpath(root, src)
          target_root = os.path.join(dst, rel_path)
          os.makedirs(target_root, exist_ok=True)
          for file in files:
              src_file = os.path.join(root, file)
              dst_file = os.path.join(target_root, file)
              # 可添加日志记录路径，方便排查
              # print(f"Copying {src_file} -> {dst_file}")
              shutil.copy2(src_file, dst_file)
  
  # 使用自定义函数替代原方法
  custom_copytree(r'Y:\package', r'\\domain\code\package')
  

• 手动遍历的方式更透明，可在关键步骤添加日志，精准定位路径异常环节

4. 环境与版本兼容性检查 #

• 对比两地Windows系统补丁版本：B地是否存在未安装的网络文件系统相关补丁，部分Windows更新可修复元数据读取异常问题
• 测试升级Python版本：将B地Python升级至3.7.x最新补丁版或3.8+版本，后续版本可能修复了os.path/shutil在网络路径下的已知bug

5. 网络稳定性排查 #

• 测试B地到DFS服务器的网络质量：用ping、tracert工具检查延迟、丢包率，网络波动可能导致os.path读取元数据时返回错误结果
• 调整网络驱动器挂载参数：尝试禁用Y:盘和DFS路径的脱机文件缓存，减少元数据读取的不一致性

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