Go os.OpenFile O_EXCL 怎样避免并发创建同名文件

在程序第一次生成状态文件、索引文件或导出结果时，最容易写出这样的逻辑：先用 os.Stat 判断文件不存在，再调用 os.Create。问题是，两个调用之间存在时间窗口，另一个 goroutine 或进程可能已经把文件创建出来。Go 里更稳妥的做法是让 os.OpenFile 在一次打开请求中同时接收 os.O_CREATE 和 os.O_EXCL：谁先成功创建，谁拿到文件；后来者得到“文件已存在”错误。

本文只讨论同一路径的独占创建、错误判断和写入收尾。O_EXCL 解决的是创建瞬间的竞争，不是分布式锁，也不替你完成写入后的完整性校验。

先检查再创建为什么会留下竞态

下面的写法看起来直观，但检查结果不能锁住后续的创建动作：

// 这段代码只演示竞态位置，不建议作为独占创建方案。
if _, err := os.Stat(path); errors.Is(err, fs.ErrNotExist) {
    // 检查通过后，另一个执行者仍可能在这里先创建 path。
    file, err := os.Create(path)
    if err != nil {
        return err
    }
    defer file.Close()
}

即使两个执行者都先观察到 fs.ErrNotExist，也不能据此推导出“我一定能创建”。如果业务要求只有一个初始化者，就应该把“不存在”和“创建”交给同一个打开操作处理。

O_CREATE 与 O_EXCL 怎样合并创建判断

os.OpenFile 接收路径、标志位和权限。O_CREATE 表示目标不存在时创建，O_EXCL 与它一起使用时要求目标不能已经存在；因此，创建动作本身就是竞争的裁决点：

package main

import (
    "errors"
    "fmt"
    "io/fs"
    "os"
)

// createOnce 只允许一个执行者创建目标文件，已存在不被当成普通写入失败。
func createOnce(path string, data []byte) error {
    // O_EXCL 必须和 O_CREATE 组合，0640 是新文件的初始权限参数。
    file, err := os.OpenFile(path, os.O_WRONLY|os.O_CREATE|os.O_EXCL, 0o640)
    if err != nil {
        // 竞争者已经创建成功时，把这个分支转成可判断的业务结果。
        if errors.Is(err, fs.ErrExist) {
            return fmt.Errorf("目标已存在：%s", path)
        }
        return fmt.Errorf("独占创建失败：%w", err)
    }

    // 写入失败时删除半成品，避免下一次把残缺文件误认成完整结果。
    if _, err := file.Write(data); err != nil {
        _ = file.Close()
        _ = os.Remove(path)
        return fmt.Errorf("写入失败：%w", err)
    }
    // Close 也可能报告错误，成功路径要把它返回给调用方。
    if err := file.Close(); err != nil {
        _ = os.Remove(path)
        return fmt.Errorf("关闭文件失败：%w", err)
    }
    return nil
}

这段函数的关键不在权限数字，而在标志组合。成功返回说明当前调用创建了这个路径；返回 fs.ErrExist 则说明创建资格已经被别的执行者占用。其它错误仍然要保留原始原因，便于区分目录不存在、权限不足和磁盘 I/O 问题。

怎样区分已存在、写入失败和关闭失败

OpenFile 的失败通常带有 *os.PathError。不要只比较错误字符串，也不要把所有错误都转换成“已存在”。使用 errors.Is(err, fs.ErrExist) 能识别存在错误，同时保留其他错误的上下文。

写入阶段也有一个容易遗漏的边界：文件已经创建，并不等于内容已经完整。示例中写入失败和关闭失败都会尝试删除半成品，但删除本身的错误不能覆盖更重要的原始错误。生产代码还可以把清理失败写入日志或作为附加错误返回，具体取决于调用方的错误模型。

什么时候不该使用 O_EXCL

还要注意，O_EXCL 只约束创建瞬间。它不会让后续多个进程对同一个文件的写入自动串行，也不能替代跨机器协调；如果创建成功后还要持续修改共享内容，应另外设计文件锁、单写者或外部协调机制。

常见问题

只写 O_EXCL 不写 O_CREATE 可以吗？

不应把它当成独占创建组合。官方定义明确说明 O_EXCL 与 O_CREATE 配合使用时要求文件不存在；创建新文件时应同时传入这两个标志。

为什么要用 fs.ErrExist 而不是比较“file exists”？

错误文本可能随平台和包装层变化。errors.Is 面向错误语义判断，能穿过 *os.PathError 等包装；原错误再用 %w 返回，调用方仍能继续判断。

创建成功后是否必须立即 Close？

必须。句柄不用时应及时关闭；如果写入或关闭失败，不能把已经创建的路径直接当成完整产物，必要时应清理半成品。

小结：把“文件不存在”和“创建成功”看成同一个竞争动作，使用 os.O_CREATE|os.O_EXCL；用 errors.Is(err, fs.ErrExist) 识别竞争失败；成功创建后仍要认真处理 Write、Close 和半成品清理。