python必背源代码复制移动文件shutil代码

木白
木白
发布时间:2026-11-17| 5人浏览过
原创

深入详解 Python 标准库 shutil 复制与移动文件、目录的必背核心源代码。全面剖析 copyfile、copy、copy2、copytree 与 move 的本质差异、元数据保留规则、跨文件系统底层机制及工业级异常防御。

在 Python 工程开发与自动化脚本中,文件和文件夹的复制、移动操作由标准库 shutil(Shell Utilities)统一承载。许多开发者在面对 copyfile、copy、copy2、copytree 和 move 时容易混淆其调用条件与元数据保留机制。本文直接给出生产环境中必须掌握的核心源代码,逐一解析每个函数在底层权限、修改时间戳、目录递归和跨文件系统移动上的行为特征,并提供防御性的健壮代码模板。
python必背源代码复制移动文件shutil代码
图 0:Python shutil 模块复制与移动操作体系架构概览

一、单文件复制三剑客: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)
python必背源代码复制移动文件shutil代码
图 1:copyfile、copy 与 copy2 复制深度与元数据保留层级对比架构

二、目录整树复制: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("目录整树递归复制完成。")
示例输出

目录整树递归复制完成。
python必背源代码复制移动文件shutil代码
图 2:文件与目录安全复制执行与异常防御标准流程

三、文件与目录移动: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() 销毁源文件。跨盘移动不具备原子性,移动大文件时应防范中途进程被杀或断电。
python必背源代码复制移动文件shutil代码
图 3:shutil.move 底层系统调用决策机制与跨文件系统数据迁移架构

四、生产环境异常防御与工业级工程模板

在实际生产环境中,文件 I/O 容易遇到目标目录不存在、源与目标相同、磁盘写满以及权限拒绝等异常。直接调用原生函数若不作防御,容易导致服务崩溃。

避坑重点:规避 shutil.SameFileError
当执行 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
python必背源代码复制移动文件shutil代码
图 4:Python shutil 复制与移动核心函数工程选型决策树与技术参数速查全景

五、核心函数选型速查与工程总结

为了在实际开发中快速定位最匹配需求的 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。
相关专题:

免责声明:本文内容仅供参考,不代表本站观点。转载或引用请注明出处。

Python 相关产品和应用

全部下载
Selenium

Selenium

4.51.0 · Windows

用于浏览器自动化和 Web 测试的 Python 工具。

scikit-learn

scikit-learn

1.9.1 · Windows

常用 Python 机器学习算法与模型评估工具库。

Black

Black

26.10.1 · Windows

强调一致性的 Python 自动代码格式化工具。

Ruff

Ruff

0.17.1 · macOS

由 Rust 编写的高速 Python 代码检查和格式化工具。

pytest

pytest

9.1.1 · Windows

简洁而强大的 Python 自动化测试框架。

FastAPI

FastAPI

0.146.0 · Windows

高性能 Python API 框架,支持类型提示和自动接口文档。

Flask

Flask

3.1.3 · Windows

轻量灵活的 Python Web 应用框架。

Django

Django

6.1.2 · Windows

成熟的 Python Web 框架,适合构建内容站点和业务系统。

Spyder

Spyder

6.1.7 · Windows

面向科学计算与数据分析的 Python 集成开发环境。

SciPy

SciPy

1.18.1 · Windows

面向科学、工程和技术计算的 Python 算法库。