Go 原子替换配置文件的临时文件方案

如果配置文件正在被读取，直接用 os.WriteFile 或先打开目标文件再截断写入，读者可能在写入中间读到不完整内容。更稳妥的做法是：在目标文件所在目录创建唯一临时文件，把完整内容写进去，调用 Sync 后关闭文件描述符，再用 os.Rename 替换目标路径。

这套方案的关键不是“把数据写到另一个文件”这么简单，而是让临时文件和目标文件处于同一目录、同一文件系统，并把 Write、Sync、Close、Rename 各自负责的事情分开。本文只讨论这个边界，不展开锁服务和多写者的事务协调。

先看直接写入为什么会暴露半截配置

假设目标路径是 config.yaml，进程先打开它并截断，再分多次写入。此时文件名没有变化，但文件内容已经处于更新中。另一个读取者只要恰好在两次写入之间打开文件，就可能读到缺少字段的 YAML 或不完整的 JSON。

临时文件替换改变的是目录项指向：旧的 config.yaml 仍然保持完整，新的内容在另一个文件中准备好；改名完成后，后续按这个名字打开的读取者看到新文件。它解决的是“读者不要看到半成品”，不是自动解决多个写入者的丢失更新。

临时文件必须创建在目标文件所在目录

os.CreateTemp 的第一个参数就是临时文件目录。不要把空字符串交给它后再指望把系统临时目录中的文件改名到配置目录：两个路径可能不在同一个文件系统，os.Rename 可能返回跨设备错误；即使某些环境恰好可用，也失去了同目录替换带来的清晰边界。

临时文件名使用目标文件名作为前缀，但让标准库追加随机部分。固定写入 config.yaml.tmp 会让两个写入协程或两个进程共享同一个中间文件，后写入者可能破坏前一个写入者的内容。

按 Write、Sync、Close、Rename 写出完整实现

下面的函数接收完整字节内容和目标权限。它先把临时文件权限设为传入值，再写入并同步文件内容；只有关闭临时文件成功后，才进行改名。任何中间步骤失败，defer 都会尝试删除临时文件。

package atomicfile

import (
    "fmt"
    "io/fs"
    "os"
    "path/filepath"
)

// Replace 在目标文件所在目录准备内容，然后用改名替换目标路径。
func Replace(path string, data []byte, perm fs.FileMode) (err error) {
    dir := filepath.Dir(path)
    base := filepath.Base(path)

    // 临时文件和目标文件同目录，避免 Rename 跨文件系统。
    f, err := os.CreateTemp(dir, "."+base+".tmp-*")
    if err != nil {
        return fmt.Errorf("create temp file: %w", err)
    }
    tempPath := f.Name()

    // 失败路径统一清理，避免配置目录积累半成品。
    defer func() {
        if err != nil {
            _ = os.Remove(tempPath)
        }
    }()

    // 新文件的权限来自临时文件，不会自动继承旧目标文件。
    if err = f.Chmod(perm); err != nil {
        _ = f.Close()
        return fmt.Errorf("chmod temp file: %w", err)
    }
    if _, err = f.Write(data); err != nil {
        _ = f.Close()
        return fmt.Errorf("write temp file: %w", err)
    }
    if err = f.Sync(); err != nil {
        _ = f.Close()
        return fmt.Errorf("sync temp file: %w", err)
    }
    if err = f.Close(); err != nil {
        return fmt.Errorf("close temp file: %w", err)
    }

    // 同目录改名替换目录项，读取者不会看到写入中的临时内容。
    if err = os.Rename(tempPath, path); err != nil {
        return fmt.Errorf("rename temp file: %w", err)
    }
    return nil
}

这里的返回值使用命名错误变量，是为了让清理逻辑知道当前调用是否失败。成功改名后，临时路径已经不存在，函数直接返回；失败时删除动作使用忽略错误的方式，不覆盖最初发生的真实错误。

Sync、Close 和 Rename 不是同一件事

Write 把字节交给操作系统，File.Sync 请求把文件内容和相关元数据同步到稳定存储，File.Close 释放文件描述符并结束对临时文件的写入，os.Rename 改变目录项的名字或指向。把这四个动作压成“写完就改名”，很难判断失败到底发生在内容、描述符还是目录项层面。

对于普通配置更新，Sync 与同目录 Rename 的组合已经比直接截断目标文件清晰得多。但如果要求在突然断电后连目录项替换也必须有严格持久化顺序，还要考虑父目录的同步；这通常需要 Unix 平台特定实现，不能仅凭跨平台的 os.Rename 宣称所有文件系统都具备相同的崩溃保证。

权限、并发和失败清理要提前定好

临时文件最终会成为新的目标文件，所以示例显式调用 Chmod。如果配置里含有凭据，权限值应按部署要求设置，而不要假设旧文件的权限会随改名自动保留下来。还应确认目标目录本身允许当前进程创建、改名和删除文件。

原子替换只处理一次写入的发布边界，不处理两个写入者同时执行“读取旧配置、修改内存、写回新配置”的竞态。需要读改写语义时，仍要在更高层使用互斥锁、租约或版本号；否则两个完整的新文件也可能互相覆盖。

失败清理也要覆盖 Write、Sync、Close 和 Rename。示例中清理函数只在命名错误非空时运行，因此成功改名后不会错误地删除已不存在的目标；清理失败不覆盖真正的系统调用错误，便于上层记录原因。

什么时候可以采用这套方案

常见问题

为什么不能把临时文件放到系统临时目录？

因为最终改名可能跨文件系统，Rename 不是跨设备复制工具。把临时文件放在目标文件所在目录，才能让替换边界稳定、失败行为可控。

调用 Close 后还需要 Sync 吗？

如果文章的目标是明确请求文件内容同步到稳定存储，应在关闭前显式调用 Sync。Close 负责结束文件使用，不应被当成等价的持久化承诺。

Rename 失败时会不会丢掉旧配置？

在同目录且目标是普通文件的常见场景中，改名失败时旧目标路径仍由调用方保留，示例还会清理未成功改名的临时文件。实际平台和目标类型仍应按部署环境处理错误。

小结

Go 原子替换配置文件的最小可靠结构是：使用 filepath.Dir 找到目标目录，用 os.CreateTemp 创建唯一临时文件，写完后调用 Sync，成功关闭描述符，再用 os.Rename 替换目标路径，同时在错误路径清理临时文件。这样可以把“内容准备”和“文件名发布”分开，也能让后续读取者避开半截配置；至于多写者协调和断电级持久化，则需要额外的上层或平台方案。