Go os.Root WriteFile 怎样避免覆盖已有文件

我在把用户提交的配置写进受限目录时，遇到过一个很容易被忽略的现场：目标文件明明已经存在，调用 Root.WriteFile 却没有报“已存在”，旧内容直接被新字节截断。这个结果不是 os.Root 失去目录边界，而是 WriteFile 本身就是“创建或覆盖”语义。

如果业务要求“只能新建，已有文件必须保留”，不要继续给 WriteFile 换权限参数。应改为 Root.OpenFile，组合 os.O_WRONLY|os.O_CREATE|os.O_EXCL，再用 errors.Is(err, os.ErrExist) 处理冲突。

官方文档：https://pkg.go.dev/os#Root.WriteFile

先看懂 WriteFile 为什么会覆盖

Root.WriteFile(name, data, perm) 的职责是把数据写到根目录树内的文件；目标不存在时创建，目标已存在时先截断再写入。官方实现等价于用 O_WRONLY|O_CREATE|O_TRUNC 打开文件，因此它不会把“已有文件”当成冲突。

package main

import (
    "fmt"
    "os"
)

func writeConfig(rootDir string, data []byte) error {
    root, err := os.OpenRoot(rootDir)
    if err != nil {
        return fmt.Errorf("打开根目录失败: %w", err)
    }
    defer root.Close() // Root 持有目录句柄，函数结束时释放它

    // WriteFile 允许创建，也允许把已有普通文件截断后重写。
    if err := root.WriteFile("config/app.json", data, 0o600); err != nil {
        return fmt.Errorf("写入配置失败: %w", err)
    }
    return nil
}

这里的 0o600 主要影响新建文件；对已经存在的文件，WriteFile 会保持原有权限，不会因为本次传入的 perm 自动改权限。更重要的是，写入过程包含打开、写入和关闭多个系统调用，中途失败可能留下部分内容，所以它也不等同于原子替换。

用 OpenFile 加 O_EXCL 拒绝已有文件

O_EXCL 必须和 O_CREATE 一起使用，含义是“创建时目标不能已经存在”。这样检查和创建由打开操作一次完成，比先 Stat、再决定是否写入更可靠，也避免两个并发调用同时通过检查。

package main

import (
    "errors"
    "fmt"
    "os"
)

func createOnly(rootDir, name string, data []byte) error {
    root, err := os.OpenRoot(rootDir)
    if err != nil {
        return fmt.Errorf("打开根目录失败: %w", err)
    }
    defer root.Close() // 释放 Root 的目录资源

    // O_EXCL 与 O_CREATE 配合：目标已存在时打开直接失败，不会截断旧文件。
    file, err := root.OpenFile(name, os.O_WRONLY|os.O_CREATE|os.O_EXCL, 0o600)
    if err != nil {
        if errors.Is(err, os.ErrExist) {
            return fmt.Errorf("目标已存在: %w", err)
        }
        return fmt.Errorf("独占创建失败: %w", err)
    }

    // Write 失败时仍要关闭文件；这里保留写入错误作为主错误。
    if _, err := file.Write(data); err != nil {
        _ = file.Close()
        return fmt.Errorf("写入新文件失败: %w", err)
    }
    if err := file.Close(); err != nil {
        return fmt.Errorf("关闭新文件失败: %w", err)
    }
    return nil
}

判断冲突时优先使用 errors.Is，不要匹配“file exists”这类英文错误文本。Go 会把系统错误包装在 *PathError 中，errors.Is 可以穿透包装判断 os.ErrExist。

父目录和 Root 路径边界要分开处理

Root 方法接收的是相对于根目录的路径。它只能访问根目录树内的对象；绝对路径、空路径或试图通过 .. 越过根目录的输入会返回错误。这个边界和“目标是否已经存在”是两类问题，不能混成一个重试逻辑。

• 父目录不存在：OpenFile 不会替你递归创建父目录；需要在业务允许时先调用 root.MkdirAll(filepath.Dir(name), 0o700)。
• 目标已存在：这是 O_EXCL 预期拒绝的业务冲突，可提示用户改名或走显式覆盖流程。
• 路径越界或不合法：应直接返回，不要把输入改写成绝对路径绕过 Root 的约束。

package main

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

func ensureParent(root *os.Root, name string) error {
    parent := filepath.Dir(name)
    if parent == "." {
        return nil // 文件就在 Root 顶层，不需要创建父目录
    }
    // MkdirAll 只接收相对 Root 的目录名，权限位仍需使用 0o777 以内的值。
    if err := root.MkdirAll(parent, 0o700); err != nil {
        return fmt.Errorf("创建父目录失败: %w", err)
    }
    return nil
}

是否自动创建父目录应由业务决定：配置写入通常可以准备固定目录，用户上传或多租户路径则更适合先做路径规范化和权限策略，再调用 Root 方法。

把写入错误和 Close 错误都收拢

只写 file.Write 而忽略 Close 的返回值，会漏掉缓冲刷新或底层关闭阶段报告的错误。示例中写入失败时先关闭资源，并保留写入错误；写入成功后再把关闭错误返回给调用方。

同时，别用“先 root.Stat(name)，不存在再 root.WriteFile”代替 O_EXCL。前者只是观察，后者才把“目标不能存在”放进创建契约里。若业务确实允许覆盖，直接使用 WriteFile；若要追加日志，使用 O_APPEND|O_CREATE|O_WRONLY，不要把追加需求误写成独占创建。

覆盖、追加和只新建怎么选

一句话记忆：WriteFile 解决“把内容写进去”，O_EXCL 解决“已有目标不能被碰”。当文件是否存在本身就是业务状态时，把这个状态交给打开标志表达，代码会比字符串判断和事前探测更清楚。

常见追问

Root.WriteFile 能通过 perm 参数禁止覆盖吗？

不能。perm 描述新建文件的权限位；已有文件仍会按 WriteFile 的覆盖语义处理。要拒绝已有目标，使用 O_CREATE|O_EXCL。

为什么不推荐先 Stat 再 WriteFile？

因为检查和写入之间存在竞态，另一个协程或进程可能在这段时间创建目标。O_EXCL 将“必须不存在”放进创建动作。

O_EXCL 能保证写入内容完整吗？

不能。它只约束打开时目标不能存在；后续写入仍可能失败或被中断。需要更强的提交语义时，应另行设计临时文件、同步和替换流程。