python必背源代码复制移动文件shutil代码
深入详解 Python 标准库 shutil 复制与移动文件、目录的必背核心源代码。全面剖析 copyfile、copy、copy2、copytree 与 move 的本质差异、元数据保留规则、跨文件系统底层机制及工业级异常防御。
copyfile、copy、copy2、copytree 和 move 时容易混淆其调用条件与元数据保留机制。本文直接给出生产环境中必须掌握的核心源代码,逐一解析每个函数在底层权限、修改时间戳、目录递归和跨文件系统移动上的行为特征,并提供防御性的健壮代码模板。
一、单文件复制三剑客:copyfile、copy 与 copy2 必背代码
Python 标准库针对单文件复制提供了三个递进的函数。三者最关键的区别不在于文件数据本身,而在于目标路径参数形式以及文件元数据(权限位、修改时间戳等)的保留完整度。
1. 纯数据流拷贝:shutil.copyfile
shutil.copyfile(src, dst) 是最底层的单文件拷贝函数。它直接将源文件的数据块流式写入目标文件,不复制任何文件元数据,且目标路径必须是一个完整的文件路径,绝不能是目录路径。
import shutil # 必背代码 1:纯二进制数据高速复制 src_file = "app/config/settings.ini" dst_file = "backup/config/settings_backup.ini" # 注意:dst_file 必须是具体文件名。若传入已存在的目录,将抛出 IsADirectoryError 或 PermissionError shutil.copyfile(src_file, dst_file) print("文件内容复制完成。")
文件内容复制完成。
2. 保留执行权限位:shutil.copy
shutil.copy(src, dst) 在完成底层数据拷贝后,会额外调用 copymode(),将源文件的 POSIX 权限标志位(例如脚本的可执行权限 +x / 0755)同步到目标文件。此外,它的 dst 参数允许传入已存在的目录,shutil 会自动以源文件名在目标目录下创建副本。
import shutil # 必背代码 2:复制脚本并保留可执行权限(dst 允许为目录路径) src_script = "deploy/start_service.sh" dst_dir = "/opt/bin/" # 必须是已存在的目录路径 # 执行后自动在 /opt/bin/ 下生成 start_service.sh,并保留源文件的 rwxr-xr-x 权限标志 result_path = shutil.copy(src_script, dst_dir) print(f"已复制到目标位置: {result_path}")
已复制到目标位置: /opt/bin/start_service.sh
3. 生产级全保真备份首选:shutil.copy2
shutil.copy2(src, dst) 是常规业务开发中最推荐使用的单文件复制函数。它不仅包含 copy() 的全部能力,还会进一步调用 copystat(),将文件的最后修改时间(st_mtime)、最后访问时间(st_atime)以及系统标志位完整复制。在数据备份、日志归档场景中,只有保留原始修改时间,后续增量检测工具与轮询脚本才能准确识别文件生命周期。
import shutil import os # 必背代码 3:完整保留元数据(时间戳、权限位)的工程备份代码 source_log = "logs/access_2026.log" target_dir = "archive/logs/" # 确保目标目录存在 os.makedirs(target_dir, exist_ok=True) # 执行高保真克隆 saved_file = shutil.copy2(source_log, target_dir) # 验证时间戳对齐 src_mtime = os.path.getmtime(source_log) dst_mtime = os.path.getmtime(saved_file) print(f"备份成功: {saved_file}") print(f"时间戳一致性检查: {src_mtime == dst_mtime} (mtime: {src_mtime})")
备份成功: archive/logs/access_2026.log
时间戳一致性检查: True (mtime: 1773532800.0)
二、目录整树复制:shutil.copytree 的递归与增量合并
当需要复制整个文件夹结构时,应当使用 shutil.copytree(src, dst)。它会递归遍历源目录下的所有子目录和文件,并在目标位置重建相同的层级体系。
1. 避免 FileExistsError:dirs_exist_ok 核心参数
在 Python 3.8 之前,若目标目录 dst 已经存在,copytree 会直接抛出 FileExistsError。从 Python 3.8 开始,引入了关键参数 dirs_exist_ok=True,允许直接向已存在的目录中合并文件,或覆盖同名文件。
2. 忽略特定文件:shutil.ignore_patterns
在项目部署、热备时,通常需要跳过编译缓存文件(如 .pyc、__pycache__)或版本控制隐藏目录(.git)。通过向 ignore 参数传入 shutil.ignore_patterns() 即可实现这一过滤。
import shutil import os # 必背代码 4:支持已存在目录合并与忽略规则的整树复制 src_dir = "/project/src" dst_dir = "/project/backup_src" # 定义过滤模式:忽略临时文件、字节码及 Git 仓库 ignore_filter = shutil.ignore_patterns( "*.pyc", "__pycache__", ".git", "*.tmp" ) shutil.copytree( src=src_dir, dst=dst_dir, symlinks=False, # 设为 False 会复制软链接指向的实体文件;设为 True 则只复制软链本身 ignore=ignore_filter, dirs_exist_ok=True # Python 3.8+ 必备参数:目标目录存在时执行合并覆盖,不报错 ) print("目录整树递归复制完成。")
目录整树递归复制完成。
三、文件与目录移动:shutil.move 必背代码与跨设备底层机制
移动操作由 shutil.move(src, dst) 统一负责。与复制函数不同,move 对单文件和整树目录一视同仁,其内部设计有着清晰的内核级优化。
1. 必背单文件与目录移动代码
import shutil import os # 必背代码 5:移动单文件并重命名 shutil.move("data/pending/report.xlsx", "data/archive/2026_report.xlsx") # 必背代码 6:将整个临时目录移动到正式发布位置 src_dir = "build/artifacts" release_dir = "release/v1.2.0" shutil.move(src_dir, release_dir) print("移动操作执行完毕。")
移动操作执行完毕。
2. 理解底层核心:同文件系统原子重命名 vs 跨分区流式降级
深入理解 shutil.move 的底层运作对于编写高可靠程序至关重要:
-
同文件系统(同一磁盘分区 / 挂载点):
shutil.move内部直接调用 POSIX 系统调用os.rename(src, dst)。这种操作只改变文件系统的目录项与 Inode 指针,不发生任何磁盘物理数据搬移。因此,无论源文件是 1KB 还是 500GB,执行耗时均在毫秒级(时间复杂度为 \(O(1)\)),并且具备操作系统层面的原子性(Atomic)。 -
跨文件系统(跨磁盘 / 跨挂载网络卷):
当源与目标处于不同设备挂载点时,
os.rename会触发操作系统内核的EXDEV错误(Invalid cross-device link)。shutil.move捕获此异常后会自动优雅降级:针对文件调用copy2(),针对目录调用copytree(),将数据完整写入目标设备,验证成功后再调用os.unlink()或rmtree()销毁源文件。跨盘移动不具备原子性,移动大文件时应防范中途进程被杀或断电。
四、生产环境异常防御与工业级工程模板
在实际生产环境中,文件 I/O 容易遇到目标目录不存在、源与目标相同、磁盘写满以及权限拒绝等异常。直接调用原生函数若不作防御,容易导致服务崩溃。
当执行
shutil.copy("a.txt", "a.txt") 或目标解析后指向同一物理 Inode 时,shutil 会抛出 shutil.SameFileError。在对未知入参进行操作前,应使用 os.path.samefile() 或 Path.resolve() 提前校验。
import os import shutil from pathlib import Path # 必背代码 7:工业级健壮单文件安全复制函数 def robust_copy_file(src_path: str, dst_path: str) -> str: """ 高保真安全复制文件: 1. 严格检查源文件存在性 2. 自动递归创建目标父级目录 3. 预防 SameFileError 自复制冲突 4. 采用 copy2 保持时间戳与权限 """ src = Path(src_path).resolve() dst = Path(dst_path).resolve() # 1. 前置校验 if not src.exists(): raise FileNotFoundError(f"源文件不存在: {src}") if not src.is_file(): raise IsADirectoryError(f"源路径不是普通文件: {src}") # 2. 目标路径规整 if dst.is_dir(): final_dst = dst / src.name else: final_dst = dst # 3. 规避同文件异常 if final_dst.exists() and os.path.samefile(src, final_dst): raise shutil.SameFileError(f"源路径与目标路径指向同一文件,禁止覆写: {src}") # 4. 确保父级目录就绪 final_dst.parent.mkdir(parents=True, exist_ok=True) # 5. 执行复制并捕获权限与系统异常 try: result = shutil.copy2(src, final_dst) return str(result) except PermissionError as e: print(f"[权限异常] 无法读取源或写入目标: {e}") raise except shutil.Error as e: print(f"[shutil 操作失败]: {e}") raise
五、核心函数选型速查与工程总结
为了在实际开发中快速定位最匹配需求的 API,下表总结了各核心函数的技术差异:
| 函数 API | 目标允许为目录 | 保留权限位 (Mode) | 保留时间戳 (mtime) | 递归子目录 | 工程应用首选场景 |
|---|---|---|---|---|---|
shutil.copyfile(src, dst) |
否 (必须是完整文件路径) | 否 (受当前 umask 限制) | 否 (更新为当前系统时间) | 否 | 极低开销纯数据拷贝、目标确定的流复制 |
shutil.copy(src, dst) |
是 (自动在目录下建同名文件) | 是 (保留可执行 +x 模式位) | 否 (更新为当前系统时间) | 否 | 分发 Shell / Python 脚本等执行文件 |
shutil.copy2(src, dst) |
是 (自动在目录下建同名文件) | 是 (完整保留权限) | 是 (完整保留原始修改时间) | 否 | 单文件工程备份、归档首选标准 |
shutil.copytree(src, dst) |
是 (必须指向目录) | 是 (递归保留) | 是 (递归保留) | 是 (整树深度遍历) | 全目录递归镜像、项目发布包打包 |
shutil.move(src, dst) |
是 (支持文件与目录) | 是 | 是 | 是 (自动识别递归) | 文件改名、跨目录整理、文件入库剪切 |
单文件备份无脑选
copy2;目录整树复制选 copytree 并开启 dirs_exist_ok=True;剪切改名统一交由 move。
本站声明
本文内容仅供参考,不代表本站观点。转载或引用请注明出处。如发现内容问题,请通过联系我们页面反馈。













