Python pathlib 怎样安全替换目录中的文件

我在更新本地配置和生成缓存文件时，最不放心的写法就是直接对正式路径使用 open(path, "w")：文件会先被截断，接着才开始写新内容，进程一旦中途退出，下一次读取可能拿到半个文件。更稳妥的做法是把完整内容写到目标目录里的临时文件，关闭它以后调用 Path.replace()，让正式路径一次切换到新文件。

直接覆盖为什么会留下半个文件

直接覆盖的危险不在 pathlib，而在更新顺序：open(..., "w") 通常先把旧内容截断，然后才接受新的字节。如果新内容很大、磁盘空间不足、编码转换出错，或者进程在写入中途退出，读者线程看到的就是一个正在变化的正式文件。

from pathlib import Path

target = Path("settings.json")

# 直接以 w 打开会先截断旧文件，写入失败时正式路径可能只剩半段内容
with target.open("w", encoding="utf-8") as file:
    file.write('{"enabled": true,')
    file.write('"region": "cn"}')

如果更新过程只涉及一个很小的临时状态，直接写入也许足够；但配置、索引、缓存快照和导出结果通常需要读者要么读到旧版本，要么读到完整新版本。接下来把“准备新内容”和“替换正式名字”拆成两个阶段。

先在目标目录写完临时文件

临时文件要通过 dir=target.parent 放到正式文件旁边。这样做的重点不是文件名好看，而是让临时路径与正式路径处在同一文件系统中，最后的替换可以使用文件系统提供的命名切换。示例还使用目标文件的后缀，便于运维人员在目录中识别它属于哪类文件。

from pathlib import Path
from tempfile import NamedTemporaryFile


def replace_text(target: Path, content: str) -> None:
    # 先创建同目录临时文件，避免跨文件系统移动
    temporary_path: Path | None = None
    try:
        with NamedTemporaryFile(
            mode="w",
            encoding="utf-8",
            dir=target.parent,
            prefix=f".{target.name}.",
            suffix=".tmp",
            delete=False,
        ) as temporary:
            temporary_path = Path(temporary.name)
            # 完整内容先写入临时文件，写入异常不会碰到正式文件
            temporary.write(content)
            temporary.flush()

        # 文件句柄已经关闭，再让临时名字接管正式路径
        temporary_path.replace(target)
        temporary_path = None
    finally:
        # 只有替换尚未成功时才清掉残留临时文件
        if temporary_path is not None:
            temporary_path.unlink(missing_ok=True)

这里的关键是 delete=False：我们需要在关闭临时文件后继续使用它的路径。写入异常会直接跳到 finally，正式文件保持原样；如果临时文件已经准备好但替换失败，也会尝试清理残留文件。

用 Path.replace 一次切换正式路径

temporary_path.replace(target) 不是把内容再次读出来复制到目标文件，而是把临时路径重命名到目标路径。Python 官方文档规定，目标是已有文件或空目录时会被无条件替换。因而替换前的正式文件不会经历“先变空、再慢慢写”的中间状态。

这一步也解释了为什么不要先把临时文件写到系统默认临时目录，再调用 replace()：如果两个路径不在同一文件系统，重命名可能失败；自行改成复制再删除，又会重新引入不完整复制和中途失败的窗口。

几个平台和数据安全边界要提前说清

第一，临时文件应创建在目标目录，不能把“系统临时目录”当成固定答案。第二，Windows 上不要在仍持有临时文件句柄时立刻用普通 open() 重开它；示例先退出 with，再替换，能避开常见的共享删除和文件占用问题。第三，replace() 解决的是名称切换，不是断电持久化；如果业务需要更强的落盘语义，还要结合文件描述符同步、目录同步和存储系统的实际能力设计。

另外，目标路径的父目录必须已经存在，且调用进程有写权限。不要把 unlink(missing_ok=True) 写成删除正式文件的补偿逻辑：它只应该作用于本次创建的临时路径。若你需要保留旧版本、回滚或审计，还应另行设计备份命名和版本记录。

最后记住这条替换配方

对配置、快照和导出文件，推荐固定成“同目录创建临时文件 → 完整写入并关闭 → Path.replace() → 失败时清理临时文件”。这套写法能把最常见的半文件问题挡在正式路径之外，但它不替你完成备份、并发锁、跨机器事务和断电恢复。把这些额外目标分别建模，文件更新才不会被一个看似安全的 API 名称误导。

相关问题

• 临时文件必须和目标文件同目录吗？不是语法上的硬要求，但同目录最容易保证最后一步是同一文件系统内的替换；跨文件系统时应重新设计复制、校验和回滚策略。
• Path.rename 和 Path.replace 有什么区别？replace() 明确表达“目标存在时也替换”，更适合本篇的覆盖更新语义；rename() 在不同平台对已存在目标的行为不同。
• replace 成功后还需要备份旧文件吗？如果业务要求回滚或审计，需要在流程中显式保留版本；原子替换本身不会自动生成备份。