Python 原子写配置文件实战：tempfile 和 os.replace 防止半截文件

很多小工具都会把配置写到本地文件，例如 settings.json、config.ini 或任务状态文件。直接打开目标文件写入看起来最简单，但线上最怕写到一半时程序被终止、磁盘空间不足，或者机器突然重启，最后留下一个半截文件。

更稳的做法是原子写入：先把新内容写到同目录的临时文件，确认写完并刷盘后，再用 os.replace() 一步替换目标文件。这样读配置的进程要么看到旧文件，要么看到新文件，不会读到半截内容。

适合人群

适合需要写本地配置、缓存索引、任务进度文件的 Python 开发者。你需要了解基础文件读写和 JSON 序列化。

目录

• 直接覆盖为什么容易留下半截文件
• 原子写入的正确流程
• 封装一个可复用的 JSON 配置保存函数
• 常见坑位和上线建议

直接覆盖为什么容易留下半截文件

直接写目标文件的风险在于：打开文件后原内容可能已经被截断，但新内容还没完整写进去。如果这时程序退出，文件就会停在一个不可解析的中间状态。对 JSON 配置来说，这种状态通常表现为少了右括号、字段只写了一半，后续服务启动时就会解析失败。

原子写入的正确流程

原子写入的关键点有三个：临时文件必须放在目标文件同一个目录，写完后要先刷新到磁盘，最后再用 os.replace() 替换。放在同目录是为了减少跨分区移动带来的不确定性；使用替换操作，是为了让文件切换尽量变成一个不可再拆的小动作。

封装一个可复用的 JSON 配置保存函数

下面的函数只使用 Python 标准库。它会把字典写成格式化 JSON，再用临时文件完成原子替换。

import json
import os
import tempfile
from pathlib import Path
from typing import Any


def save_json_atomic(path: str, data: dict[str, Any]) -> None:
    target = Path(path)
    target.parent.mkdir(parents=True, exist_ok=True)

    text = json.dumps(data, ensure_ascii=False, indent=2) + "\n"
    fd, temp_name = tempfile.mkstemp(
        prefix=f".{target.name}.",
        suffix=".tmp",
        dir=str(target.parent),
        text=True,
    )

    try:
        with os.fdopen(fd, "w", encoding="utf-8") as handle:
            handle.write(text)
            handle.flush()
            os.fsync(handle.fileno())

        os.replace(temp_name, target)
    except BaseException:
        try:
            os.unlink(temp_name)
        except FileNotFoundError:
            pass
        raise

调用方式很简单：

config = {
    "debug": False,
    "workers": 4,
    "api_base": "https://api.example.local",
}

save_json_atomic("runtime/settings.json", config)

如果写入过程失败，目标文件仍然保留旧内容；如果替换完成，读配置的代码会看到完整的新内容。

常见坑位和上线建议

1. 临时文件不要放到系统临时目录

很多人会把临时文件放在默认临时目录，但这可能和目标文件不在同一个分区。稳妥做法是把临时文件放在目标文件同目录，减少替换时的意外情况。

2. 写完后不要忘记刷新

flush() 会把 Python 缓冲区推给操作系统，os.fsync() 会进一步要求落到磁盘。对重要配置来说，这一步能降低机器异常退出时丢内容的概率。

3. 异常时清理临时文件

写入失败后，隐藏临时文件可能留在目录里。上面的代码在异常分支里做了清理，避免目录里堆满无用文件。

4. 多进程同时写要加锁

原子替换解决的是“读到半截文件”的问题，不解决“多个进程抢着写”的问题。如果多个进程可能同时保存同一个配置，还需要额外加文件锁或集中到单个写入服务。

小结

Python 写配置文件时，直接覆盖目标文件虽然省事，但遇到中断容易留下半截内容。使用 tempfile.mkstemp() 写同目录临时文件，再通过 flush()、os.fsync() 和 os.replace() 完成替换，可以让本地配置保存更稳，特别适合命令行工具、桌面小工具和轻量任务系统。